diff options
Diffstat (limited to 'doc/trouble.html')
| -rw-r--r-- | doc/trouble.html | 706 |
1 files changed, 706 insertions, 0 deletions
diff --git a/doc/trouble.html b/doc/trouble.html new file mode 100644 index 000000000..2123f3805 --- /dev/null +++ b/doc/trouble.html @@ -0,0 +1,706 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd"> +<HTML> +<HEAD> +<TITLE>Introduction to FreeS/WAN</TITLE> +<META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=iso-8859-1"> +<STYLE TYPE="text/css"><!-- +BODY { font-family: serif } +H1 { font-family: sans-serif } +H2 { font-family: sans-serif } +H3 { font-family: sans-serif } +H4 { font-family: sans-serif } +H5 { font-family: sans-serif } +H6 { font-family: sans-serif } +SUB { font-size: smaller } +SUP { font-size: smaller } +PRE { font-family: monospace } +--></STYLE> +</HEAD> +<BODY> +<A HREF="toc.html">Contents</A> +<A HREF="firewall.html">Previous</A> +<A HREF="compat.html">Next</A> +<HR> +<H1><A NAME="trouble"></A>Linux FreeS/WAN Troubleshooting Guide</H1> +<H2><A NAME="overview"></A>Overview</H2> +<P> This document covers several general places where you might have a + problem:</P> +<OL> +<LI><A HREF="#install">During install</A>.</LI> +<LI><A HREF="#negotiation">During the negotiation process</A>.</LI> +<LI><A HREF="#use">Using an established connection</A>.</LI> +</OL> +<P>This document also contains<A HREF="#notes"> notes</A> which expand + on points made in these sections, and tips for<A HREF="#prob.report"> + problem reporting</A>. If the other end of your connection is not + FreeS/WAN, you'll also want to read our<A HREF="interop.html#interop.problem"> + interoperation</A> document.</P> +<H2><A NAME="install"></A>1. During Install</H2> +<H3><A NAME="8_2_1">1.1 RPM install gotchas</A></H3> +<P>With the RPM method:</P> +<UL> +<LI>Be sure you have installed both the userland tools and the kernel + components. One will not work without the other. For example, when + using FreeS/WAN-produced RPMs for our 2.04 release, you need both: +<PRE> freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm + freeswan-module-2.04_2.4.20_20.9-0.i386.rpm +</PRE> +</LI> +</UL> +<H3><A NAME="8_2_2">1.2 Problems installing from source</A></H3> +<P>When installing from source, you may find these problems:</P> +<UL> +<LI>Missing library. See<A HREF="faq.html#gmp.h_missing"> this</A> FAQ.</LI> +<LI>Missing utilities required for compile. See this<A HREF="install.html#tool.lib"> + checklist</A>.</LI> +<LI>Kernel version incompatibility. See<A HREF="faq.html#k.versions"> + this</A> FAQ.</LI> +<LI>Another compile problem. Find information in the out.* files, ie. + out.kpatch, out.kbuild, created at compile time in the top-level Linux + FreeS/WAN directory. Error messages generated by KLIPS during the boot + sequence are accessible with the<VAR> dmesg</VAR> command. +<BR> Check the list archives and the List in Brief to see if this is a + known issue. If it is not, report it to the bugs list as described in + our<A HREF="#prob.report"> problem reporting</A> section. In some + cases, you may be asked to provide debugging information using gdb; + details<A HREF="#gdb"> below</A>.</LI> +<LI>If your kernel compiles but you fail to install your new + FreeS/WAN-enabled kernel, review the sections on<A HREF="install.html#newk"> + installing the patched kernel</A>, and<A HREF="install.html#testinstall"> + testing</A> to see if install succeeded.</LI> +</UL> +<H3><A NAME="install.check"></A>1.3 Install checks</H3> +<P><VAR>ipsec verify</VAR> checks a number of FreeS/WAN essentials. Here + are some hints on what do to when your system doesn't check out:</P> +<P></P> +<TABLE border="1"> +<TR><TD><STRONG>Problem</STRONG></TD><TD><STRONG>Status</STRONG></TD><TD> +<STRONG>Action</STRONG></TD></TR> +<TR><TD><VAR>ipsec</VAR> not on-path</TD><TD> </TD><TD> +<P>Add<VAR> /usr/local/sbin</VAR> to your PATH.</P> +</TD></TR> +<TR><TD>Missing KLIPS support</TD><TD><FONT COLOR="#FF0000">critical</FONT> +</TD><TD>See<A HREF="faq.html#noKLIPS"> this FAQ.</A></TD></TR> +<TR><TD>No RSA private key</TD><TD> </TD><TD> +<P>Follow<A HREF="install.html#genrsakey"> these instructions</A> to + create an RSA key pair for your host. RSA keys are:</P> +<UL> +<LI>required for opportunistic encryption, and</LI> +<LI>our preferred method to authenticate pre-configured connections.</LI> +</UL> +</TD></TR> +<TR><TD><VAR>pluto</VAR> not running</TD><TD><FONT COLOR="#FF0000"> +critical</FONT></TD><TD> +<PRE>service ipsec start</PRE> +</TD></TR> +<TR><TD>No port 500 hole</TD><TD><FONT COLOR="#FF0000">critical</FONT></TD><TD> +Open port 500 for IKE negotiation.</TD></TR> +<TR><TD>Port 500 check N/A</TD><TD> </TD><TD>Check that port 500 is open + for IKE negotiation.</TD></TR> +<TR><TD>Failed DNS checks</TD><TD> </TD><TD>Opportunistic encryption + requires information from DNS. To set this up, see<A HREF="quickstart.html#opp.setup"> + our instructions</A>.</TD></TR> +<TR><TD>No public IP address</TD><TD> </TD><TD>Check that the interface + which you want to protect with IPSec is up and running.</TD></TR> +</TABLE> +<H3><A NAME="oe.trouble"></A>1.3 Troubleshooting OE</H3> +<P>OE should work with no local configuration, if you have posted DNS + TXT records according to the instructions in our<A HREF="quickstart.html"> + quickstart guide</A>. If you encounter trouble, try these hints. We + welcome additional hints via the<A HREF="mail.html"> users' mailing + list</A>.</P> +<TABLE border="1"> +<TR><TD><STRONG>Symptom</STRONG></TD><TD><STRONG>Problem</STRONG></TD><TD> +<STRONG>Action</STRONG></TD></TR> +<TR><TD> You're running FreeS/WAN 2.01 (or later), and initiating a + connection to FreeS/WAN 2.00 (or earlier). In your logs, you see a + message like: +<PRE>no RSA public key known for '192.0.2.13'; +DNS search for KEY failed (no KEY record +for 13.2.0.192.in-addr.arpa.)</PRE> + The older FreeS/WAN logs no error.</TD><TD><A NAME="oe.trouble.flagday"> +</A> A protocol level incompatibility between 2.01 (or later) and 2.00 + (or earlier) causes this error. It occurs when a FreeS/WAN 2.01 (or + later) box for which no KEY record is posted attempts to initiate an OE + connection to older FreeS/WAN versions (2.00 and earlier). Note that + older versions can initiate to newer versions without this error.</TD><TD> +If you control the peer host, upgrade its FreeS/WAN to 2.01 (or later), + and post new style TXT records for it. If not, but if you know its + sysadmin, perhaps a quick note is in order. If neither option is + possible, you can ease the transition by posting an old style KEY + record (created with a command like "ipsec showhostkey --key") to the + reverse map for the FreeS/WAN 2.01 (or later) box.</TD></TR> +<TR><TD>OE host is very slow to contact other hosts.</TD><TD>Slow DNS + service while running OE.</TD><TD>It's a good idea to run a caching DNS + server on your OE host, as outlined in<A HREF="http://lists.freeswan.org/pipermail/design/2003-January/004205.html"> + this mailing list message</A>. If your DNS servers are elsewhere, put + their IPs in the<VAR> clear</VAR> policy group, and re-read groups with +<PRE>ipsec auto --rereadgroups</PRE> +</TD></TR> +<TR><TD> +<PRE>Can't Opportunistically initiate for +192.0.2.2 to 192.0.2.3: no TXT record +for 13.2.0.192.in-addr.arpa.</PRE> +</TD><TD>Peer is not set up for OE.</TD><TD> +<P>None. Plenty of hosts on the Internet do not run OE. If, however, you + have set OE up on that peer, this may indicate that you need to wait up + to 48 hours for its DNS records to propagate.</P> +</TD></TR> +<TR><TD><VAR>ipsec verify</VAR> does not find DNS records: +<PRE>... +Looking for TXT in forward map: + xy.example.com...[FAILED] +Looking for TXT in reverse map...[FAILED] +...</PRE> + You also experience authentication failure: +<BR> +<PRE>Possible authentication failure: +no acceptable response to our +first encrypted message</PRE> +</TD><TD>DNS records are not posted or have not propagated.</TD><TD>Did + you post the DNS records necessary for OE? If not, do so using the + instructions in our<A HREF="quickstart.html#quickstart"> quickstart + guide</A>. If so, wait up to 48 hours for the DNS records to propagate.</TD> +</TR> +<TR><TD><VAR>ipsec verify</VAR> does not find DNS records, and you + experience authentication failure.</TD><TD>For iOE, your ID does not + match location of forward DNS record.</TD><TD>In<VAR> config setup</VAR> +, change<VAR> myid=</VAR> to match the forward DNS where you posted the + record. Restart FreeS/WAN. For reference, see our<A HREF="quickstart.html#opp.client"> + iOE instructions</A>.</TD></TR> +<TR><TD><VAR>ipsec verify</VAR> finds DNS records, yet there is still + authentication failure. ( ? )</TD><TD>DNS records are malformed.</TD><TD> +Re-create the records and send new copies to your DNS administrator.</TD> +</TR> +<TR><TD><VAR>ipsec verify</VAR> finds DNS records, yet there is still + authentication failure. ( ? )</TD><TD>DNS records show different keys + for a gateway vs. its subnet hosts.</TD><TD>All TXT records for boxes + protected by an OE gateway must contain the gateway's public key. + Re-create and re-post any incorrect records using<A HREF="quickstart.html#opp.incoming"> + these instructions</A>.</TD></TR> +<TR><TD>OE gateway loses connectivity to its subnet. The gateway's + routing table shows routes to the subnet through IPsec interfaces.</TD><TD> +The subnet is part of the<VAR> private</VAR> or<VAR> block</VAR> policy + group on the gateway.</TD><TD>Remove the subnet from the group, and + reread groups with +<PRE>ipsec auto --rereadgroups</PRE> +</TD></TR> +<TR><TD>OE does not work to hosts on the local LAN.</TD><TD>This is a + known issue.</TD><TD>See<A HREF="opportunism.known-issues"> this list</A> + of known issues with OE.</TD></TR> +<TR><TD>FreeS/WAN does not seem to be executing your default policy. In + your logs, you see a message like: +<PRE>/etc/ipsec.d/policies/iprivate-or-clear" +line 14: subnet "0.0.0.0/0", +source 192.0.2.13/32, +already "private-or-clear"</PRE> +</TD><TD><A HREF="glossary.html#fullnet">Fullnet</A> in a policy group + file defines your default policy. Fullnet should normally be present in + only one policy group file. The fine print: you can have two default + policies defined so long as they protect different local endpoints + (e.g. the FreeS/WAN gateway and a subnet).</TD><TD> Find all policies + which contain fullnet with: +<BR> +<PRE>grep -F 0.0.0.0/0 /etc/ipsec.d/policies/*</PRE> + then remove the unwanted occurrence(s).</TD></TR> +</TABLE> +<H2><A NAME="negotiation"></A>2. During Negotiation</H2> +<P>When you fail to bring up a tunnel, you'll need to find out:</P> +<UL> +<LI><A HREF="#state">what your connection state is,</A> and often</LI> +<LI><A HREF="#find.pluto.error">an error message</A>.</LI> +</UL> +<P>before you can<A HREF="#interpret.pluto.error"> diagnose your problem</A> +.</P> +<H3><A NAME="state"></A>2.1 Determine Connection State</H3> +<H4>Finding current state</H4> +<P>You can see connection states (STATE_MAIN_I1 and so on) when you + bring up a connection on the command line. If you have missed this, or + brought up your connection automatically, use:</P> +<PRE>ipsec auto --status</PRE> +<P>The most relevant state is the last one reached.</P> +<H4><VAR>What's this supposed to look like?</VAR></H4> +<P>Negotiations should proceed though various states, in the processes + of:</P> +<OL> +<LI>IKE negotiations (aka Phase 1, Main Mode, STATE_MAIN_*)</LI> +<LI>IPSEC negotiations (aka Phase 2, Quick Mode, STATE_QUICK_*)</LI> +</OL> +<P>These are done and a connection is established when you see messages + like:</P> +<PRE> 000 #21: "myconn" STATE_MAIN_I4 (ISAKMP SA established)... + 000 #2: "myconn" STATE_QUICK_I2 (sent QI2, IPsec SA established)...</PRE> +<P> Look for the key phrases are "ISAKMP SA established" and "IPSec SA + established", with the relevant connection name. Often, this happens at + STATE_MAIN_I4 and STATE_QUICK_I2, respectively.</P> +<P><VAR>ipsec auto --status</VAR> will tell you what states<STRONG> have + been achieved</STRONG>, rather than the current state. Since + determining the current state is rather more difficult to do, current + state information is not available from Linux FreeS/WAN. If you are + actively bringing a connection up, the status report's last states for + that connection likely reflect its current state. Beware, though, of + the case where a connection was correctly brought up but is now downed: + Linux FreeS/WAN will not notice this until it attempts to rekey. + Meanwhile, the last known state indicates that the connection has been + established.</P> +<P>If your connection is stuck at STATE_MAIN_I1, skip straight to<A HREF="#ikepath"> + here</A>.</P> +<H3><A NAME="find.pluto.error"></A>2.2 Finding error text</H3> +<P>Solving most errors will require you to find verbose error text, + either on the command line or in the logs.</P> +<H4>Verbose start for more information</H4> +<P> Note that you can get more detail from<VAR> ipsec auto</VAR> using + the --verbose flag:</P> +<PRE STYLE="margin-bottom: 0.2in"> ipsec auto --verbose --up west-east</PRE> +<P> More complete information can be gleaned from the<A HREF="#logusage"> + log files</A>.</P> +<H4>Debug levels count</H4> +<P>The amount of description you'll get here depends on ipsec.conf debug + settings,<VAR> klipsdebug</VAR>= and<VAR> plutodebug</VAR>=. When + troubleshooting, set at least one of these to<VAR> all</VAR>, and when + done, reset it to<VAR> none</VAR> so your logs don't fill up. Note that + you must have enabled the<VAR> klipsdebug</VAR><A HREF="install.html#allbut"> + compile-time option</A> for the<VAR> klipsdebug</VAR> configuration + switch to work.</P> +<P>For negotiation problems<VAR> plutodebug</VAR> is most relevant.<VAR> + klipsdebug</VAR> applies mainly to attempts to use an + already-established connection. See also<A HREF="ipsec.html#parts"> + this</A> description of the division of duties within Linux FreeS/WAN.</P> +<P>After raising your debug levels, restart Linux FreeS/WAN to ensure + that ipsec.conf is reread, then recreate the error to generate verbose + logs.</P> +<H4><VAR>ipsec barf</VAR> for lots of debugging information</H4> +<P><A HREF="manpage.d/ipsec_barf.8.html"><VAR> ipsec barf (8)</VAR></A> + collects a bunch of useful debugging information, including these logs + Use the command</P> +<PRE> + ipsec barf > barf.west +</PRE> +<P>to generate one.</P> +<H4>Find the error</H4> +<P>Search out the failure point in your logs. Are there a handful of + lines which succinctly describe how things are going wrong or contrary + to your expectation? Sometimes the failure point is not immediately + obvious: Linux FreeS/WAN's errors are usually not marked "Error". Have + a look in the<A HREF="faq.html"> FAQ</A> for what some common failures + look like.</P> +<P>Tip: problems snowball. Focus your efforts on the first problem, + which is likely to be the cause of later errors.</P> +<H4>Play both sides</H4> +<P>Also find error text on the peer IPSec box. This gives you two + perspectives on the same failure.</P> +<P>At times you will require information which only one side has. The + peer can merely indicate the presence of an error, and its approximate + point in the negotiations. If one side keeps retrying, it may be + because there is a show stopper on the other side. Have a look at the + other side and figure out what it doesn't like.</P> +<P>If the other end is not Linux FreeS/WAN, the principle is the same: + replicate the error with its most verbose logging on, and capture the + output to a file.</P> +<H3><A NAME="interpret.pluto.error"></A>2.3 Interpreting a Negotiation + Error</H3> +<H4><A NAME="ikepath"></A>Connection stuck at STATE_MAIN_I1</H4> +<P>This error commonly happens because IKE (port 500) packets, needed to + negotiate an IPSec connection, cannot travel freely between your IPSec + gateways. See<A HREF="firewall.html#packets"> our firewall document</A> + for details.</P> +<H4>Other errors</H4> +<P>Other errors require a bit more digging. Use the following resources:</P> +<UL> +<LI><A HREF="faq.html">the FAQ</A> . Since this document is constantly + updated, the snapshot's FAQ may have a new entry relevant to your + problem.</LI> +<LI>our<A HREF="background.html"> background document</A> . Special + considerations which, while not central to Linux FreeS/WAN, are often + tripped over. Includes problems with<A href="background.html#MTU.trouble"> + packet fragmentation</A>, and considerations for testing opportunism.</LI> +<LI>the<A HREF="mail.html#lists"> list archives</A>. Each of the + searchable archives works differently, so it's worth checking each. Use + a search term which is generic, but identifies your error, for example + "No connection is known for". +<BR> Often, you will find that your question has been answered in the + past. Finding an archived answer is quicker than asking the list. You + may, however, find similar questions without answers. If you do, send + their URLs to the list with your trouble report. The additional + examples may help the list tech support person find your answer.</LI> +<LI>Look into the code where the error is being generated. The pluto + code is nicely documented with comments and meaningful variable names.</LI> +</UL> +<P>If you have failed to solve your problem with the help of these + resources, send a detailed problem report to the users list, following + these<A HREF="#prob.report"> guidelines</A>.</P> +<H2><A NAME="use"></A>3. Using a Connection</H2> +<H3><A NAME="8_4_1">3.1 Orienting yourself</A></H3> +<H4><VAR>How do I know if it works?</VAR></H4> +<P>Test your connection by sending packets through it. The simplest way + to do this is with ping, but the ping needs to<STRONG> test the correct + tunnel.</STRONG> See<A HREF="#testgates"> this example scenario</A> if + you don't understand this.</P> +<P></P> +<P>If your ping returns, test any other connections you've brought u all + check out, great. You may wish to<A HREF="#bigpacket"> test with large + packets</A> for MTU problems.</P> +<H4><VAR>ipsec barf</VAR> is useful again</H4> +<P>If your ping fails to return, generate an ipsec barf debugging report + on each IPSec gateway. On a non-Linux FreeS/WAN implementation, gather + equivalent information. Use this, and the tips in the next sections, to + troubleshoot. Are you sure that both endpoints are capable of hearing + and responding to ping?</P> +<H3><A NAME="8_4_2">3.2 Those pesky configuration errors</A></H3> +<P>IPSec may be dropping your ping packets since they do not belong in + the tunnels you have constructed:</P> +<UL> +<LI>Your ping may not test the tunnel you intend to test. For details, + see our<A HREF="faq.html#cantping"> "I can't ping"</A> FAQ.</LI> +<LI> Alternately, you may have a configuration error. For example, you + may have configured one of the four possible tunnels between two + gateways, but not the one required to secure the important traffic + you're now testing. In this case, add and start the tunnel, and try + again.</LI> +</UL> +<P>In either case, you will often see a message like:</P> +<PRE>klipsdebug... no eroute</PRE> +<P>which we discuss in<A HREF="faq.html#no_eroute"> this FAQ</A>.</P> +<P>Note:</P> +<UL> +<LI><A HREF="glossary.html#NAT.gloss">Network Address Translation (NAT)</A> + and<A HREF="glossary.html#masq"> IP masquerade</A> may have an effect + on which tunnels you need to configure.</LI> +<LI>When testing a tunnel that protects a multi-node subnet, try several + subnet nodes as ping targets, in case one node is routing incorrectly.</LI> +</UL> +<H3><A NAME="route.firewall"></A>3.3 Check Routing and Firewalling</H3> +<P>If you've confirmed your configuration assumptions, the problem is + almost certainly with routing or firewalling. Isolate the problem using + interface statistics, firewall statistics, or a packet sniffer.</P> +<H4>Background:</H4> +<UL> +<LI>Linux FreeS/WAN supplies all the special routing it needs; you need + only route packets out through your IPSec gateway. Verify that on the<VAR> + subnetted</VAR> machines you are using for your ping-test, your routing + is as expected. I have seen a tunnel "fail" because the subnet machine + sending packets out an alternate gateway (not our IPSec gateway) on + their return path.</LI> +<LI>Linux FreeS/WAN requires particular<A HREF="firewall.html"> + firewalling considerations</A>. Check the firewall rules on your IPSec + gateways and ensure that they allow IPSec traffic through. Be sure that + no other machine - for example a router between the gateways - is + blocking your IPSec packets.</LI> +</UL> +<H4><A NAME="ifconfig"></A>View Interface and Firewall Statistics</H4> +<P>Interface reports and firewall statistics can help you track down + lost packets at a glance. Check any firewall statistics you may be + keeping on your IPSec gateways, for dropped packets.</P> +<P><STRONG>Tip</STRONG>: You can take a snapshot of the packets + processed by your firewall with:</P> +<PRE> iptables -L -n -v</PRE> +<P>You can get creative with "diff" to find out what happens to a + particular packet during transmission.</P> +<P>Both<VAR> cat /proc/net/dev</VAR> and<VAR> ifconfig</VAR> display + interface statistics, and both are included in<VAR> ipsec barf</VAR>. + Use either to check if any interface has dropped packets. If you find + that one has, test whether this is related to your ping. While you ping + continuously, print that interface's statistics several times. Does its + drop count increase in proportion to the ping? If so, check why the + packets are dropped there.</P> +<P>To do this, look at the firewall rules that apply to that interface. + If the interface is an IPSec interface, more information may be + available in the log. Grep for the word "drop" in a log which was + created with<VAR> klipsdebug=all</VAR> as the error happened.</P> +<P>See also this<A HREF="#ifconfig1"> discussion</A> on interpreting<VAR> + ifconfig</VAR> statistics.</P> +<H3><A NAME="sniff"></A>3.4 When in doubt, sniff it out</H3> +<P>If you have checked configuration assumptions, routing, and firewall + rules, and your interface statistics yield no clue, it remains for you + to investigate the mystery of the lost packet by the most thorough + method: with a packet sniffer (providing, of course, that this is legal + where you are working).</P> +<P>In order to detect packets on the ipsec virtual interfaces, you will + need an up-to-date sniffer (tcpdump, ethereal, ksnuffle) on your IPSec + gateway machines. You may also find it useful to sniff the ping + endpoints.</P> +<H4>Anticipate your packets' path</H4> +<P>Ping, and examine each interface along the projected path, checking + for your ping's arrival. If it doesn't get to the the next stop, you + have narrowed down where to look for it. In this way, you can isolate a + problem area, and narrow your troubleshooting focus.</P> +<P>Within a machine running Linux FreeS/WAN, this<A HREF="firewall.html#packets"> + packet flow diagram</A> will help you anticipate a packet's path.</P> +<P>Note that:</P> +<UL> +<LI> from the perspective of the tunneled packet, the entire tunnel is + one hop. That's explained in<A HREF="faq.html#no_trace"> this</A> FAQ.</LI> +<LI> an encapsulated IPSec packet will look different, when sniffed, + from the plaintext packet which generated it. You can see plaintext + packets entering an IPSec interface and the resulting cyphertext + packets as they emerge from the corresponding physical interface.</LI> +</UL> +<P>Once you isolate where the packet is lost, take a closer look at + firewall rules, routing and configuration assumptions as they affect + that specific area. If the packet is lost on an IPSec gateway, comb + through<VAR> klipsdebug</VAR> output for anomalies.</P> +<P>If the packet goes through both gateways successfully and reaches the + ping target, but does not return, suspect routing. Check that the ping + target routes packets back to the IPSec gateway.</P> +<H3><A NAME="find.use.error"></A>3.5 Check your logs</H3> +<P>Here, too, log information can be useful. Start with the<A HREF="#find.pluto.error"> + guidelines above</A>.</P> +<P>For connection use problems, set<VAR> klipsdebug=all</VAR>. Note that + you must have enabled the<VAR> klipsdebug</VAR><A HREF="install.html#allbut"> + compile-time option</A> to do this. Restart Linux FreeS/WAN so that it + rereads<VAR> ipsec.conf</VAR>, then recreate the error condition. When + searching through<VAR> klipsdebug</VAR> data, look especially for the + keywords "drop" (as in dropped packets) and "error".</P> +<P>Often the problem with connection use is not software error, but + rather that the software is behaving contrary to expectation.</P> +<H4><A NAME="interpret.use.error"></A>Interpreting log text</H4> +<P>To interpret the Linux FreeS/WAN log text you've found, use the same + resources as indicated for troubleshooting connection negotiation:<A HREF="faq.html"> + the FAQ</A> , our<A HREF="background.html"> background document</A>, + and the<A HREF="mail.html#lists"> list archives</A>. Looking in the + KLIPS code is only for the very brave.</P> +<P>If you are still stuck, send a<A HREF="#prob.report"> detailed + problem report</A> to the users' list.</P> +<H3><A NAME="bigpacket"></A>3.6 More testing for the truly thorough</H3> +<H4>Large Packets</H4> +<P>If each of your connections passed the ping test, you may wish to + test by pinging with large packets (2000 bytes or larger). If it does + not return, suspect MTU issues, and see this<A HREF="background.html#MTU.trouble"> + discussion</A>.</P> +<H4>Stress Tests</H4> +<P>In most users' view, a simple ping test, and perhaps a large-packet + ping test suffice to indicate a working IPSec connection.</P> +<P>Some people might like to do additional stress tests prior to + production use. They may be interested in this<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/12/msg00224.html"> + testing protocol</A> we use at interoperation conferences, aka + "bakeoffs". We also have a<VAR> testing</VAR> directory that ships with + the release.</P> +<H2><A NAME="prob.report"></A>4. Problem Reporting</H2> +<H3><A NAME="8_5_1">4.1 How to ask for help</A></H3> +<P>Ask for troubleshooting help on the users' mailing list,<A HREF="mailto:users@lists.freeswan.org"> + users@lists.freeswan.org</A>. While sometimes an initial query with a + quick description of your intent and error will twig someone's memory + of a similar problem, it's often necessary to send a second mail with a + complete problem report.</P> +<P>When reporting problems to the mailing list(s), please include:</P> +<UL> +<LI>a brief description of the problem</LI> +<LI>if it's a compile problem, the actual output from make, showing the + problem. Try to edit it down to only the relevant part, but when in + doubt, be as complete as you can. If it's a kernel compile problem, any + relevant out.* files</LI> +<LI>if it's a run-time problem, pointers to where we can find the + complete output from "ipsec barf" from BOTH ENDS (not just one of + them). Remember that it's common outside the US and Canada to pay for + download volume, so if you can't post barfs on the web and send the URL + to the mailing list, at least compress them with tar or gzip. +<BR> If you can, try to simplify the case that is causing the problem. + In particular, if you clear your logs, start FreeS/WAN with no other + connections running, cause the problem to happen, and then do<VAR> + ipsec barf</VAR> on both ends immediately, that gives the smallest and + least cluttered output.</LI> +<LI>any other error messages, complaints, etc. that you saw. Please send + the complete text of the messages, not just a summary.</LI> +<LI>what your network setup is. Include subnets, gateway addresses, etc. + A schematic diagram is a good format for this information.</LI> +<LI>exactly what you were trying to do with Linux FreeS/WAN, and exactly + what went wrong</LI> +<LI>a fix, if you have one. But remember, you are sending mail to people + all over the world; US residents and US citizens in particular, please + read doc/exportlaws.html before sending code -- even small bug fixes -- + to the list or to us.</LI> +<LI>When in doubt about whether to include some seemingly-trivial item + of information, include it. It is rare for problem reports to have too + much information, and common for them to have too little.</LI> +</UL> +<P>Here are some good general guidelines on bug reporting:<A href="http://tuxedo.org/~esr/faqs/smart-questions.html"> + How To Ask Questions The Smart Way</A> and<A href="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html"> + How to Report Bugs Effectively</A>.</P> +<H3><A NAME="8_5_2">4.2 Where to ask</A></H3> +<P>To report a problem, send mail about it to the users' list. If you + are certain that you have found a bug, report it to the bugs list. If + you encounter a problem while doing your own coding on the Linux + FreeS/WAN codebase and think it is of interest to the design team, + notify the design list. When in doubt, default to the users' list. More + information about the mailing lists is found<A HREF="mail.html#lists"> + here</A>.</P> +<P>For a number of reasons -- including export-control regulations + affecting almost any<STRONG> private</STRONG> discussion of encryption + software -- we prefer that problem reports and discussions go to the + lists, not directly to the team. Beware that the list goes worldwide; + US citizens, read this important information about your<A HREF="politics.html#exlaw"> + export laws</A>. If you're using this software, you really should be on + the lists. To get onto them, visit<A HREF="http://lists.freeswan.org/"> + lists.freeswan.org</A>.</P> +<P>If you do send private mail to our coders or want a private reply + from them, please make sure that the return address on your mail (From + or Reply-To header) is a valid one. They have more important things to + do than to unravel addresses that have been mangled in an attempt to + confuse spammers.</P> +<H2><A NAME="notes"></A>5. Additional Notes on Troubleshooting</H2> +<P>The following sections supplement the Guide:<A HREF="#system.info"> + information available on your system</A>;<A HREF="#testgates"> testing + between security gateways</A>;<A HREF="#ifconfig1"> ifconfig reports + for KLIPS debugging</A>;<A HREF="#gdb"> using GDB on Pluto</A>.</P> +<H3><A NAME="system.info"></A>5.1 Information available on your system</H3> +<H4><A NAME="logusage"></A>Logs used</H4> +<P>Linux FreeS/WAN logs to:</P> +<UL> +<LI>/var/log/secure (or, on Debian, /var/log/auth.log)</LI> +<LI>/var/log/messages</LI> +</UL> +<P>Check both places to get full information. If you find nothing, check + your<VAR> syslogd.conf(5)</VAR> to see where your /etc/syslog.conf or + equivalent is directing<VAR> authpriv</VAR> messages.</P> +<H4><A NAME="pages"></A>man pages provided</H4> +<DL> +<DT><A HREF="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</A></DT> +<DD> Manual page for IPSEC configuration file.</DD> +<DT><A HREF="manpage.d/ipsec.8.html"> ipsec(8)</A></DT> +<DD STYLE="margin-bottom: 0.2in"> Primary man page for ipsec utilities.</DD> +</DL> +<P> Other man pages are on<A HREF="manpages.html"> this list</A> and in</P> +<UL> +<LI>/usr/local/man/man3</LI> +<LI>/usr/local/man/man5</LI> +<LI>/usr/local/man/man8/ipsec_*</LI> +</UL> +<H4><A NAME="statusinfo"></A>Status information</H4> +<DL> +<DT>ipsec auto --status</DT> +<DD> Command to get status report from running system. Displays Pluto's + state. Includes the list of connections which are currently "added" to + Pluto's internal database; lists state objects reflecting ISAKMP and + IPsec SAs being negotiated or installed.</DD> +<DT> ipsec look</DT> +<DD> Brief status info.</DD> +<DT> ipsec barf</DT> +<DD STYLE="margin-bottom: 0.2in"> Copious debugging info.</DD> +</DL> +<H3><A NAME="testgates"></A> 5.2 Testing between security gateways</H3> +<P>Sometimes you need to test a subnet-subnet tunnel. This is a tunnel + between two security gateways, which protects traffic on behalf of the + subnets behind these gateways. On this network:</P> +<PRE> Sunset==========West------------------East=========Sunrise + IPSec gateway IPSec gateway + local net untrusted net local net</PRE> +<P> you might name this tunnel sunset-sunrise. You can test this tunnel + by having a machine behind one gateway ping a machine behind the other + gateway, but this is not always convenient or even possible.</P> +<P>Simply pinging one gateway from the other is not useful. Such a ping + does not normally go through the tunnel.<STRONG> The tunnel handles + traffic between the two protected subnets, not between the gateways</STRONG> + . Depending on the routing in place, a ping might</P> +<UL> +<LI>either succeed by finding an unencrypted route</LI> +<LI>or fail by finding no route. Packets without an IPSEC eroute are + discarded.</LI> +</UL> +<P><STRONG>Neither event tells you anything about the tunnel</STRONG>. + You can explicitly create an eroute to force such packets through the + tunnel, or you can create additional tunnels as described in our<A HREF="config.html#multitunnel"> + configuration document</A>, but those may be unnecessary complications + in your situation.</P> +<P>The trick is to explicitly test between<STRONG> both gateways' + private-side IP addresses</STRONG>. Since the private-side interfaces + are on the protected subnets, the resulting packets do go via the + tunnel. Use either ping -I or traceroute -i, both of which allow you to + specify a source interface. (Note: unsupported on older Linuxes). The + same principles apply for a road warrior (or other) case where only one + end of your tunnel is a subnet.</P> +<H3><A NAME="ifconfig1"></A>5.3 ifconfig reports for KLIPS debugging</H3> +<P>When diagnosing problems using ifconfig statistics, you may wonder + what type of activity increments a particular counter for an ipsecN + device. Here's an index, posted by KLIPS developer Richard Guy Briggs:</P> +<PRE>Here is a catalogue of the types of errors that can occur for which +statistics are kept when transmitting and receiving packets via klips. +I notice that they are not necessarily logged in the right counter. +. . . + +Sources of ifconfig statistics for ipsec devices + +rx-errors: +- packet handed to ipsec_rcv that is not an ipsec packet. +- ipsec packet with payload length not modulo 4. +- ipsec packet with bad authenticator length. +- incoming packet with no SA. +- replayed packet. +- incoming authentication failed. +- got esp packet with length not modulo 8. + +tx_dropped: +- cannot process ip_options. +- packet ttl expired. +- packet with no eroute. +- eroute with no SA. +- cannot allocate sk_buff. +- cannot allocate kernel memory. +- sk_buff internal error. + + +The standard counters are: + +struct enet_statistics +{ + int rx_packets; /* total packets received */ + int tx_packets; /* total packets transmitted */ + int rx_errors; /* bad packets received */ + int tx_errors; /* packet transmit problems */ + int rx_dropped; /* no space in linux buffers */ + int tx_dropped; /* no space available in linux */ + int multicast; /* multicast packets received */ + int collisions; + + /* detailed rx_errors: */ + int rx_length_errors; + int rx_over_errors; /* receiver ring buff overflow */ + int rx_crc_errors; /* recved pkt with crc error */ + int rx_frame_errors; /* recv'd frame alignment error */ + int rx_fifo_errors; /* recv'r fifo overrun */ + int rx_missed_errors; /* receiver missed packet */ + + /* detailed tx_errors */ + int tx_aborted_errors; + int tx_carrier_errors; + int tx_fifo_errors; + int tx_heartbeat_errors; + int tx_window_errors; +}; + +of which I think only the first 6 are useful.</PRE> +<H3><A NAME="gdb"></A> 5.4 Using GDB on Pluto</H3> +<P>You may need to use the GNU debugger, gdb(1), on Pluto. This should + be necessary only in unusual cases, for example if you encounter a + problem which the Pluto developer cannot readily reproduce or if you + are modifying Pluto.</P> +<P>Here are the Pluto developer's suggestions for doing this:</P> +<PRE>Can you get a core dump and use gdb to find out what Pluto was doing +when it died? + +To get a core dump, you will have to set dumpdir to point to a +suitable directory (see <A HREF="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</A>). + +To get gdb to tell you interesting stuff: + $ script + $ cd dump-directory-you-chose + $ gdb /usr/local/lib/ipsec/pluto core + (gdb) where + (gdb) quit + $ exit + +The resulting output will have been captured by the script command in +a file called "typescript". Send it to the list. + +Do not delete the core file. I may need to ask you to print out some +more relevant stuff.</PRE> +<P> Note that the<VAR> dumpdir</VAR> parameter takes effect only when + the IPsec subsystem is restarted -- reboot or ipsec setup restart.</P> +<P> +<BR> +<BR></P> +<HR> +<A HREF="toc.html">Contents</A> +<A HREF="firewall.html">Previous</A> +<A HREF="compat.html">Next</A> +</BODY> +</HTML> |