3 <TITLE>FreeS/WAN troubleshooting</TITLE>
4 <meta name="keywords" content="Linux, IPSEC, VPN, security, FreeSWAN, troubleshooting, debugging">
6 Written by Claudia Schmeing for the Linux FreeS/WAN project
7 Freely distributable under the GNU General Public License
9 More information at www.freeswan.org
10 Feedback to users@lists.freeswan.org
13 RCS ID: $Id: trouble.html,v 1.21 2001/12/29 17:06:09 sandy Exp $
14 Last changed: $Date: 2001/12/29 17:06:09 $
15 Revision number: $Revision: 1.21 $
17 CVS revision numbers do not correspond to FreeS/WAN release numbers.
23 <H1><A NAME="guide"></A>Linux FreeS/WAN Troubleshooting Guide</H1>
25 <H2><A NAME="overview"></A>Overview</H2>
28 Before we launch into how to establish, test and troubleshoot a
29 connection step by step, here's a brief overview that may allow you
30 to skim ahead to the most useful part of this document for you.</P>
32 There are several general places where you might have a problem:</P>
34 <LI><P><A HREF="#install">During install</A>.</P>
35 <LI><P><A HREF="#before">Before connection negotiation</A>.</P>
36 <LI><P><A HREF="#negotiation">During the negotiation process</A>.</P>
37 <LI><P><A HREF="#use">Using an established connection</A>.</P>
39 <P>This document also contains <A HREF="#notes">notes</A> which
40 expand on points made in these sections, and tips for <A HREF="#prob.report">problem
41 reporting</A>. If the other end of your connection is not FreeS/WAN,
42 see also our <A HREF="interop.html#interop.problem">interoperation</A>
44 <H2><A NAME="install"></A>1. During Install</H2>
45 <P>Instructions and tips are in our <A HREF="install.html">install
46 document</A>. If you encounter a problem, it may be:</P>
48 <LI><P>Missing library. See <A HREF="faq.html#gmp.h_missing">this</A>
50 <LI><P>Missing utilities required for compile. See this <A HREF="install.html#tool.lib">checklist</A>.</P>
51 <LI><P>Kernel version incompatibility. See <A HREF="faq.html#k.versions">this</A>
53 <LI><P>Another compile problem. Find information in the out.* files,
54 ie. out.kpatch, out.kbuild, created at compile time in the top-level
55 Linux FreeS/WAN directory. Error messages generated by KLIPS during
56 the boot sequence are accessible with the <VAR>dmesg</VAR> command
58 <P>Check the list archives and the List in Brief to see if this is a
59 known issue. If it is not, report it to the bugs list as described
60 in our <A HREF="#prob.report">problem reporting</A> section. In some
61 cases, you may be asked to provide debugging information using gdb;
62 details <A HREF="#gdb">below</A>.</P>
63 <LI><P>If your kernel compiles but you fail to install your new
64 FreeS/WAN-enabled kernel, review the sections on <A HREF="install.html#newk">installing
65 the patched kernel</A>, and <A HREF="install.html#testinstall">testing</A>
66 to see if install succeeded.</P>
68 <H2><A NAME="before"></A>2. Before Connection Negotiation</H2>
69 <H3><A NAME="plan"></A>2.1 Plan your tunnels</H3>
70 <P>Know your IPSec needs. For most people who begin experimenting
71 with IPSec in the field, your configuration will more or less
72 resemble one of the samples in our <A HREF="config.html">configuration
73 document</A> . Other folks may wish to create a testbed network in a
74 lab environment for intensive IPSec testing or proof-of-concept. They
75 may be interested in <A HREF="testing.html#testnet">this description</A>
76 of a sample testbed network.</P>
77 <H3>2.2 Configure Step by Step</H3>
78 <P>Draw a network schematic. This will assist others in helping you
79 should you mail the list for help.</P>
81 <PRE>Sunset==========West------------------East
82 corporate LAN untrusted net</PRE><P>
83 Add IPs to the diagram.</P>
84 <PRE>Sunset==========West------------------East
85 corporate LAN untrusted net
89 eth0(external)=N.N.N.222
91 eth1(internal)=192.168.1.1;
92 gateway for 192.168.0.0/24</PRE><P>
93 How many tunnels do you need to connect your sites sufficiently for
94 your purposes? Check our <A HREF="config.html#multitunnel">configuration
95 document</A> for why you might need multiple tunnels. How would you
97 <P>Above, it is possible to make two tunnels: sunset-east and
98 west-east. If East does not need to access any resources on West, <STRONG>and
99 West is not masquerading</STRONG> (see below) we may only want to
100 create sunset-east. Sunset-east is a tunnel between IPSec-enabled
101 machines West and East, created to protect traffic between the net on
102 which Sunset resides, and East. However, it is safest to create all
103 potential tunnels in your configuration. This lowers the risk that
104 you will forget to configure a needed tunnel, and send important data
105 cleartext. As an added safeguard, by default, (at the time of
106 writing) Linux FreeS/WAN prevents you from routing cleartext packets
107 between IPSec gateways which are also linked by a tunnel. Reliance on
108 this behaviour is not a substitute for secure network design.</P>
109 <P>Take into account any masquerading and Network Address Translation
110 rules on your gateway. If you are masquerading packets from Sunset as
111 they leave West, Linux FreeS/WAN will treat these as though they
112 originated at West, not Sunset. For more detail, see this <A HREF="firewall.html#packets">packet
113 flow diagram</A>.</P>
114 <P>For each tunnel, think of a packet path that will allow you to
115 test that tunnel. Refer to <A HREF="#testgates">this discussion</A>.</P>
116 <H3><A NAME="ikepath"></A>2.3 Ensure a Clear Path for IKE</H3>
117 <P>Ensure that IKE packets can travel freely between your IPSec
118 gateways, as described <A HREF="firewall.html#packets">here</A>. If
119 they cannot, the connection negotiation, described below, will be
120 stuck in its first state.</P>
121 <H2><A NAME="negotiation"></A>3. During Negotiation</H2>
122 <H3><A NAME="establish"></A>3.1 Create a connection</H3>
123 <P>Bring up one of your connections, using the ipsec auto commands at
126 <PRE STYLE="margin-bottom: 0.2in"> ipsec auto --add west-east</PRE><P>
128 <PRE STYLE="margin-bottom: 0.2in"> ipsec auto --up west-east</PRE><P>
129 At this stage of testing, do not bring up the connections by the
130 alternate method, using ipsec.conf's <VAR>auto=</VAR> directive. You
131 want to view the output as it happens.</P>
132 <P>If the resulting status report shows that you have established an
133 ISAKMP and an IPSec Security Association (aka "SA", loosely
134 translated as "tunnel" or "connection"), your
135 tunnel is up. Repeat for each tunnel you are testing.</P>
136 <P>If negotiations for any one tunnel fail, troubleshoot as indicated
137 in the next section. If you have successfully established all desired
138 tunnels, proceed to <A HREF="#use">test your connection(s)</A> below.
139 If you find that each tunnel in a multitunnel config may be created
140 individually, but all may not be created at once, you may have
141 encountered an old (1.6) bug. Update your Linux FreeS/WAN.</P>
142 <H3><A NAME="state"></A>3.1.1 Determine Connection State</H3>
143 <P>When you bring a tunnel up from the command line, you see a report
144 on the negotiations involved in creating the connection, as these
145 happen. There are also:
148 <LI><P>ipsec look, which provides a brief status report</P>
149 <LI><P>ipsec auto --status, included in the barf</P>
150 <LI><P>log files. More information about the log files is available
151 <A HREF="#logusage">here</A>.
154 <P>Often, the most relevant state information appears last in a log
155 or status report.</P>
156 <P>Negotiations will proceed through various states. You will know
157 these are done and a connection is established when you see both
159 <PRE> 000 #21: "myconn" STATE_MAIN_I4 (ISAKMP SA established)...
160 000 #2: "myconn" STATE_QUICK_I2 (sent QI2, IPsec SA established)...</PRE><P>
161 The key phrases are "ISAKMP SA established" and "IPSec
162 SA established", which should appear with the relevant
163 connection name. Often, this happens at STATE_MAIN_I4 and
164 STATE_QUICK_I2, respectively.</P>
165 <P>A note on ipsec auto --status: this will tell you what states <STRONG>have
166 been achieved</STRONG>, rather than the current state. Since
167 determining the current state is rather more difficult to do, current
168 state information is not available from Linux FreeS/WAN. If you are
169 actively bringing a connection up, the status report's last states
170 for that connection likely reflect its current state. Beware, though,
171 of the case where a connection was correctly brought up but is now
172 downed: Linux FreeS/WAN will not notice this until it attempts to
173 rekey. Meanwhile, the last known state indicates that the connection
174 has been established.</P>
175 <P>Linux FreeS/WAN proceeds though IKE (Phase 1, Main Mode,
176 STATE_MAIN_*) negotiations first, then begins IPSec (Phase 2, Quick
177 Mode, STATE_QUICK_*) negotiations. If you do not see success, note
178 the place where negotiations stopped. This information is useful,
179 since there are common errors specific to certain points in the
181 <H3><A NAME="find.error"></A>3.2 Find a Negotiation Error</H3>
182 <P>Look for verbose error text in the logs. While ipsec --auto dialog
183 will tell you at which state Linux FreeS/WAN failed, it lacks detail.
184 You can get more detail by modifying it with the --verbose flag on
185 each invocation. For example:</P>
186 <PRE STYLE="margin-bottom: 0.2in"> ipsec auto --verbose --up west-east</PRE><P>
187 Complete information can be gleaned from the <A HREF="#logusage">log
189 <P>The amount of description in the logs depends on ipsec.conf debug
190 settings, <VAR>klipsdebug</VAR>= and <VAR>plutodebug</VAR>=. See
191 the <A HREF="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</A> man page
192 for details. You will normally want to set these to
193 either "none" or "all". Note that you must have
194 enabled the <VAR>klipsdebug</VAR> <A HREF="install.html#allbut">compile-time
195 option</A> for the <VAR>klipsdebug</VAR> configuration switch to
197 <P>For negotiation problems, <VAR>plutodebug</VAR> is most relevant.
198 <VAR>klipsdebug</VAR> applies mainly to attempts to use an
199 already-established connection. See also <A HREF="ipsec.html#parts">this</A>
200 description of the division of duties within Linux FreeS/WAN.</P>
201 <P>After raising your debug levels, restart Linux FreeS/WAN to ensure
202 that ipsec.conf is reread, then recreate the error to generate
206 This is a good time to produce a barf file, a collection of
207 information useful for debugging Linux FreeS/WAN on your system. Use
210 ipsec barf > barf.west
212 See also the <A HREF="manpage.d/ipsec_barf.8.html">ipsec_barf(8)</A>
215 Look at the logs within the resulting file, and find the failure
216 point. Are there a handful of lines which succinctly describe how
217 things are going wrong or contrary to your expectation? Sometimes the
218 failure point is not immediately obvious: Linux FreeS/WAN's errors
219 are usually not marked "Error". Have a look in the <A HREF="faq.html">FAQ</A>
220 for what some common failures look like. Tip: problems snowball.
221 Focus your efforts on the first problem, which is likely to be the
222 cause of later errors.</P>
223 <P>Repeat the process to find meaningful error text on the peer IPSec
224 box. If the other end is not Linux FreeS/WAN, get it to produce
225 detailed log output while you replicate the error, then capture that
226 output to a file.</P>
227 <P>It is useful if both ends store information about the same event
228 from two perspectives. Sometimes you will require information which
229 only one side has. In this case, the peer can merely indicate the
230 presence of an error, and its approximate point in the negotiations.
231 If one side keeps retrying, it may be because there is a show stopper
232 on the other side. Have a look at the other side and figure out what
234 <H3><A NAME="interpret.error"></A>3.2.1 Interpret a Negotiation Error</H3>
235 <P>To interpret Linux FreeS/WAN log text, use the following
238 <LI><P><A HREF="faq.html">the FAQ</A> . Since this document is
239 constantly updated, the snapshot's FAQ may have a new entry relevant
241 <LI><P>our <A HREF="background.html">background document</A> .
242 Special considerations which, while not central to Linux FreeS/WAN,
243 are often tripped over. Includes problems with
244 <a href="background.html#MTU.trouble">packet fragmentation</a>,
245 and considerations for
246 testing opportunism.</P>
247 <LI><P>the <A HREF="mail.html#lists">list archives</A>. Each of the
248 searchable archives works differently, so it's worth checking each.
249 Use a search term which is generic, but identifies your error, for
250 example "No connection is known for".</P>
251 <P>Often, you will find that your question has been answered in the
252 past. Finding an archived answer is quicker than asking the list.
253 You may, however, find similar questions without answers. If you do,
254 send their URLs to the list with your trouble report. The additional
255 examples may help the list tech support person find your answer.</P>
256 <LI><P>Look into the code where the error is being generated. The
257 pluto code is nicely documented with comments and meaningful
260 <P>If you have failed to solve your problem with the help of these
261 resources, send a detailed problem report to the users list,
262 following these <A HREF="#prob.report">guidelines</A>.</P>
263 <H2><A NAME="use"></A>4. Using a Connection</H2>
264 <H3><A NAME="test"></A>4.1 Ping test</H3>
265 <P>Test a connection by sending packets through it. The simplest way
266 to do this is with ping. Remember, in the <A HREF="#before">planning
267 stage</A>, choosing a path which would test the tunnel? Now, ping
270 <P>If your ping returns, test any other connections you've brought
271 up. If they all check out, great. You may wish to <A HREF="#bigpacket">test
272 with large packets</A> for MTU problems.</P>
273 <P>If your ping fails to return, generate an ipsec barf debugging
274 report on each IPSec gateway. On a non-Linux FreeS/WAN
275 implementation, gather equivalent information. Use this, and the tips
276 in the next sections, to troubleshoot. Are you sure that both
277 endpoints are capable of hearing and responding to ping?</P>
278 <H4><A NAME="check.path"></A>4.1.1 Check your ping path</H4>
279 <P>IPSec may be dropping your ping packets since it does not "think"
280 they belong in the tunnels you have constructed. This is an error
281 about assumptions, and it takes two forms.</P>
282 <P>In the first, your ping is not returning because its path does not
283 fall within your tunnel. This ping does not test the tunnel you
284 intend to test. Referring to this <A HREF="#testgates">discussion</A>
285 about appropriate tests, determine an alternate ping path which <STRONG>would</STRONG>
288 <P>In the second form of this error, you have not correctly
289 configured the functionality you want. In the example above, you may
290 have configured one of the possible tunnels between West and East
291 (say west-east) but not the tunnel required to secure the important
292 traffic you're now testing (say a sunset-east tunnel to secure
293 traffic between office net Sunset and laptop East). See also <A HREF="faq.html#cantping">this
294 FAQ </A>titled "I can't ping". NAT and masquerading may
295 have an effect on which tunnels you need to configure; that's
296 discussed in "<A HREF="#before">Before there's trouble</A>".</P>
297 <P>Both forms show identical symptoms. After all, the difference is
298 one of intent. In both forms, Linux FreeS/WAN receives a packet
299 destined for a peer IPSec gateway. Finding no active tunnel in which
300 this packet belongs, it drops the packet on the floor. If your debug
301 levels are appropriate, it logs this with a "klipsdebug... no
302 eroute" message, which is discussed in <A HREF="faq.html#no_eroute">this
305 <P>Note: When testing a tunnel that protects a multi-node subnet, you
306 may wish to try several subnet nodes as ping targets, in case one
307 node is routing incorrectly.</P>
308 <H3><A NAME="route.firewall"></A>4.2 Check Routing and Firewalling</H3>
309 <P>If you've confirmed your configuration assumptions, the problem is
310 almost certainly with routing or firewalling. Isolate the problem
311 using interface statistics, firewall statistics, or a packet sniffer.</P>
314 <LI><P>Linux FreeS/WAN supplies all the special routing it needs;
315 you need only route packets out through your IPSec gateway. Verify
316 that on the machines you are using for your ping-test, your routing
317 is as expected. I have seen a tunnel "fail" because the
318 subnet machine was not routing packets back to the IPSec gateway;
319 rather, it routed them through an alternate gateway.</P>
320 <LI><P>Linux FreeS/WAN requires special firewalling considerations,
321 described in our <A HREF="firewall.html">firewalling</A> document.
322 Check the firewall rules on your IPSec gateways and ensure that they
323 allow IPSec traffic through. Be sure that no other machine - for
324 example a router between the gateways - is blocking your IPSec
327 <H4><A NAME="ifconfig"></A>4.2.1 View Interface and Firewall
329 <P>Interface reports and firewall statistics can help you track down
330 lost packets at a glance.
332 <P>Check any firewall statistics you may be keeping on your IPSec
333 gateways, for dropped packets.</P>
334 <P>Both <VAR>cat /proc/net/dev</VAR> and <VAR>ifconfig</VAR> display
335 interface statistics, and both are included in an ipsec barf. Use
336 either to check if any interface has dropped packets. If you find
337 that one has, test whether this is related to your ping. While you
338 ping continuously, print that interface's statistics several times.
339 Does its drop count increase in proportion to the ping? If so, check
340 why the packets are dropped there.</P>
341 <P>Check the firewall rules that apply to that interface. If the
342 interface is an IPSec interface, more information may be available in
343 the log. Grep for the word "drop" in a log which was
344 created with <VAR>klipsdebug=all</VAR> as the error happened.</P>
345 <P>See also <A HREF="#ifconfig1">this</A> detailed discussion by
346 KLIPS programmer Richard Guy Briggs on interpreting <VAR>ifconfig</VAR>.</P>
347 <H3><A NAME="sniff"></A>4.3 Sniff packets</H3>
348 <P>If you have checked configuration assumptions, routing, and
349 firewall rules, and your interface statistics yield no clue, it
350 remains for you to investigate the mystery of the lost packet by the
351 most thorough method: with a packet sniffer. Sniff packets at each
352 interface along the projected ping path until you find where your
353 packets disappear. In this way, you can isolate the problem area, and
354 narrow your troubleshooting focus.</P>
355 <P>Install an up-to-date sniffer (tcpdump, ethereal, ksnuffle) on
356 your IPSec gateway machines. A sniffer on the ping endpoints is also
357 useful. The sniffer should be somewhat modern (tcpdump 3.3+,
358 ethereal-0.8.18) so that you may view packets on the ipsec virtual
359 interface as well as the underlying physical one.</P>
360 <P>Working from your schematic, anticipate your ping's path. Which
361 machines will your ping be visible on, in which order? Now, which
362 interfaces will it be visible on, in which order? Within a machine
363 running Linux FreeS/WAN, this <A HREF="firewall.html#packets">packet
364 flow diagram</A> will help you anticipate the packet's path. Note
365 that from the perspective of the tunneled packet, the entire tunnel
366 is one hop. That's explained in <A HREF="faq.html#no_trace">this</A>
368 <P>Ping, and as you do, sniff the packets. Examine each interface
369 along the projected path, checking for your ping's arrival. If it
370 doesn't arrive at the next stop, you have narrowed down where to look
373 <P>Note that an encapsulated IPSec packet will look different, when
374 sniffed, from the plaintext packet which generated it. However, you
375 can observe plaintext packets entering an IPSec interface and the
376 resulting cyphertext packets as they emerge from the corresponding
379 <P>Once you isolate where the packet is lost, take a closer look at
380 firewall rules, routing and configuration assumptions as they affect
381 that specific area. If the packet is lost on an IPSec gateway, comb
382 through <VAR>klipsdebug</VAR> output for anomalies.
384 <P>If the packet goes through both gateways successfully and reaches
385 the ping target, but does not return, suspect routing. Check that the
386 ping target routes packets back to the IPSec gateway.</P>
387 <H3><A NAME="find.use.error"></A>4.4 Find a Connection Use Error</H3>
388 <P>The guidelines are the same as for the Pluto logs, <A HREF="#find.error">above</A>.</P>
389 <P>For connection use problems, set <VAR>klipsdebug=all</VAR>. Note
390 that you must have enabled the <VAR>klipsdebug</VAR> <A HREF="install.html#allbut">compile-time
391 option</A> to do this. Restart Linux FreeS/WAN so that it rereads the
392 configuration file, then recreate the error condition. When searching
393 through <VAR>klipsdebug</VAR> data, look especially for the keywords
394 "drop" (as in dropped packets) and "error".</P>
395 <P>Often the problem with connection use is not software error, but
396 rather that the software is behaving contrary to expectation.
398 <H4><A NAME="interpret.use.error"></A>4.4.1 Interpret a Connection
400 <P>To interpret the Linux FreeS/WAN log text you've found, use the
401 same resources as indicated for troubleshooting <A HREF="#interpret.error">connection
402 negotiation</A>: <A HREF="faq.html">the FAQ</A> , our
403 <A HREF="background.html">background
404 document</A> , and the <A HREF="mail.html#lists">list archives</A>.
405 Looking in the KLIPS code is recommended only for the brave.</P>
406 <P>If you are still stuck, send a <A HREF="#prob.report">detailed
407 problem report</A> to the users' list.</P>
408 <H3><A NAME="bigpacket"></A>4.4 Test with Large Packets</H3>
409 <P>If each of your connections passed the ping test, you may wish to
410 test by pinging with large packets (2000 bytes or larger). If it does
411 not return, suspect MTU issues, and see this <A HREF="background.html#MTU.trouble">discussion</A>.</P>
412 <H3>4.5 Stress Tests</H3>
413 <P>In most users' view, a simple ping test, and perhaps a
414 large-packet ping test suffice to indicate a working IPSec
416 <P>Some people might like to do additional stress tests prior to
417 production use. They may be interested in this <A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/12/msg00224.html">testing
418 protocol</A> we use at interoperation conferences, aka "bakeoffs".
419 We also have a <VAR>testing</VAR> directory that ships with the
421 <H2><A NAME="prob.report"></A>5. Problem Reporting</H2>
422 <H3>5.1 How to ask for help</H3>
423 <P>Ask for troubleshooting help on the users' mailing list,
424 <A HREF="mailto:users@lists.freeswan.org">users@lists.freeswan.org</A>.
425 While sometimes an initial query with a quick description of your
426 intent and error will twig someone's memory of a similar problem,
427 it's often necessary to send a second mail with a complete problem
430 <P>The essay <A HREF="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">How
431 to Report Bugs Effectively</A> contains good guidelines.
433 <P>When reporting problems to the mailing list(s), please include:
436 <LI><P>a brief description of the problem</P>
437 <LI><P>if it's a compile problem, the actual output from make,
438 showing the problem. Try to edit it down to only the relevant part,
439 but when in doubt, be as complete as you can. If it's a kernel
440 compile problem, any relevant out.* files</P>
441 <LI><P>if it's a run-time problem, pointers to where we can find the
442 complete output from "ipsec barf" from BOTH ENDS (not just
443 one of them). Remember that it's common outside the US and Canada to
444 pay for download volume, so if you can't post barfs on the web and
445 send the URL to the mailing list, at least compress them with tar or
447 <P>If you can, try to simplify the case that is causing the problem.
448 In particular, if you clear your logs, start FreeS/WAN with no other
449 connections running, cause the problem to happen, and then do <VAR>ipsec
450 barf</VAR> on both ends immediately, that gives the smallest and
451 least cluttered output.</P>
452 <LI><P>any other error messages, complaints, etc. that you saw.
453 Please send the complete text of the messages, not just a summary.</P>
454 <LI><P>what your network setup is. Include subnets, gateway
455 addresses, etc. The <A HREF="#before">network schematic</A> is a
456 good format for this information.</P>
457 <LI><P>exactly what you were trying to do with Linux FreeS/WAN, and
458 exactly what went wrong</P>
459 <LI><P>a fix, if you have one. But remember, you are sending mail to
460 people all over the world; US residents and US citizens in
461 particular, please read doc/exportlaws.html before sending code --
462 even small bug fixes -- to the list or to us.</P>
463 <LI><P>When in doubt about whether to include some seemingly-trivial
464 item of information, include it. It is rare for problem reports to
465 have too much information, and common for them to have too little.</P>
467 <H3>5.2 Where to ask</H3>
468 <P>To report a problem, send mail about it to the users' list. If you
469 are certain that you have found a bug, report it to the bugs list. If
470 you encounter a problem while doing your own coding on the Linux
471 FreeS/WAN codebase and think it is of interest to the design team,
472 notify the design list. When in doubt, default to the users' list.
473 More information about the mailing lists is found <A HREF="mail.html#lists">here</A>.</P>
474 <P>For a number of reasons -- including export-control regulations
475 affecting almost any <STRONG>private</STRONG> discussion of
476 encryption software -- we prefer that problem reports and discussions
477 go to the lists, not directly to the team. Beware that the list goes
478 worldwide; US citizens, read this important information about your
479 <A HREF="politics.html#exlaw">export laws</A>. If you're using this
480 software, you really should be on the lists. To get onto them, visit
481 <A HREF="http://lists.freeswan.org/">lists.freeswan.org</A>.</P>
482 <P>If you do send private mail to our coders or want a private reply
483 from them, please make sure that the return address on your mail
484 (From or Reply-To header) is a valid one. They have more important
485 things to do than to unravel addresses that have been mangled in an
486 attempt to confuse spammers.
488 <H2><A NAME="notes"></A>6. Additional Notes on Troubleshooting</H2>
489 <P>The following sections supplement the Guide: <A HREF="#system.info">information
490 available on your system</A>; <A HREF="#testgates">testing between
491 security gateways</A>; <A HREF="#ifconfig1">ifconfig reports for
492 KLIPS debugging</A>; <A HREF="#gdb">using GDB on Pluto</A>.</P>
493 <H3><A NAME="system.info"></A>6.1 Information available on your
495 <H4><A NAME="logusage"></A>6.1.1 Logs used</H4>
496 <P>Linux FreeS/WAN logs to:</P>
498 <LI><P STYLE="margin-bottom: 0in">/var/log/secure (or, on Debian,
501 <LI><P>/var/log/messages
504 <P>Check both places to get full information. If you find nothing,
505 check your <VAR>syslogd.conf(5)</VAR> to see where your
506 /etc/syslog.conf or equivalent is directing <VAR>authpriv</VAR>
508 <H4><A NAME="pages"></A>6.1.2 man pages provided</H4>
510 <DT><A HREF="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</A>
512 Manual page for IPSEC configuration file.
514 <A HREF="manpage.d/ipsec.8.html">ipsec(8)</A>
515 </DT><DD STYLE="margin-bottom: 0.2in">
516 Primary man page for ipsec utilities.
519 Other man pages are on <A HREF="manpages.html">this list</A> and in</P>
521 <LI><P STYLE="margin-bottom: 0in">/usr/local/man/man3
523 <LI><P STYLE="margin-bottom: 0in">/usr/local/man/man5
525 <LI><P>/usr/local/man/man8/ipsec_*
528 <H4><A NAME="statusinfo"></A>6.1.3 Status information</H4>
530 <DT>ipsec auto --status
532 Command to get status report from running system. Displays Pluto's
533 state. Includes the list of connections which are currently "added"
534 to Pluto's internal database; lists state objects reflecting ISAKMP
535 and IPsec SAs being negotiated or installed.
542 </DT><DD STYLE="margin-bottom: 0.2in">
543 Copious debugging info.
546 <A NAME="testgates"></A>6.2 Testing between security gateways</H3>
547 <P>Sometimes you need to test a subnet-subnet tunnel. This is a
548 tunnel between two security gateways, which protects traffic on
549 behalf of the subnets behind these gateways. On this network:</P>
550 <PRE> Sunset==========West------------------East=========Sunrise
551 IPSec gateway IPSec gateway
552 local net untrusted net local net</PRE><P>
553 you might name this tunnel sunset-sunrise. You can test this tunnel
554 by having a machine behind one gateway ping a machine behind the
555 other gateway, but this is not always convenient or even possible.</P>
556 <P>Simply pinging one gateway from the other is not useful. Such a
557 ping does not normally go through the tunnel. <STRONG>The tunnel
558 handles traffic between the two protected subnets, not between the
559 gateways</STRONG> . Depending on the routing in place, a ping might</P>
561 <LI><P STYLE="margin-bottom: 0in">either succeed by finding an
564 <LI><P>or fail by finding no route. Packets without an IPSEC eroute
568 <P><STRONG>Neither event tells you anything about the tunnel</STRONG>.
569 You can explicitly create an eroute to force such packets through the
570 tunnel, or you can create additional tunnels as described in our
571 <A HREF="config.html#multitunnel">configuration document</A>, but
572 those may be unnecessary complications in your situation.</P>
573 <P>The trick is to explicitly test between <STRONG>both gateways'
574 private-side IP addresses</STRONG>. Since the private-side interfaces
575 are on the protected subnets, the resulting packets do go via the
576 tunnel. Use either ping -I or traceroute -i, both of which allow you
577 to specify a source interface. (Note: unsupported on older Linuxes).
578 The same principles apply for a road warrior (or other) case where
579 only one end of your tunnel is a subnet.</P>
580 <H3><A NAME="ifconfig1"></A>6.3 ifconfig reports for KLIPS debugging</H3>
581 <P>When diagnosing problems using ifconfig statistics, you may wonder
582 what type of activity increments a particular counter for an ipsecN
583 device. Here's an index, posted by KLIPS developer Richard Guy
585 <PRE>Here is a catalogue of the types of errors that can occur for which
586 statistics are kept when transmitting and receiving packets via klips.
587 I notice that they are not necessarily logged in the right counter.
590 Sources of ifconfig statistics for ipsec devices
593 - packet handed to ipsec_rcv that is not an ipsec packet.
594 - ipsec packet with payload length not modulo 4.
595 - ipsec packet with bad authenticator length.
596 - incoming packet with no SA.
598 - incoming authentication failed.
599 - got esp packet with length not modulo 8.
602 - cannot process ip_options.
603 - packet ttl expired.
604 - packet with no eroute.
606 - cannot allocate sk_buff.
607 - cannot allocate kernel memory.
608 - sk_buff internal error.
611 The standard counters are:
613 struct enet_statistics
615 int rx_packets; /* total packets received */
616 int tx_packets; /* total packets transmitted */
617 int rx_errors; /* bad packets received */
618 int tx_errors; /* packet transmit problems */
619 int rx_dropped; /* no space in linux buffers */
620 int tx_dropped; /* no space available in linux */
621 int multicast; /* multicast packets received */
624 /* detailed rx_errors: */
625 int rx_length_errors;
626 int rx_over_errors; /* receiver ring buff overflow */
627 int rx_crc_errors; /* recved pkt with crc error */
628 int rx_frame_errors; /* recv'd frame alignment error */
629 int rx_fifo_errors; /* recv'r fifo overrun */
630 int rx_missed_errors; /* receiver missed packet */
632 /* detailed tx_errors */
633 int tx_aborted_errors;
634 int tx_carrier_errors;
636 int tx_heartbeat_errors;
637 int tx_window_errors;
640 of which I think only the first 6 are useful.</PRE><H3>
641 <A NAME="gdb"></A>6.4 Using GDB on Pluto</H3>
642 <P>You may need to use the GNU debugger, gdb(1), on Pluto. This
643 should be necessary only in unusual cases, for example if you
644 encounter a problem which the Pluto developer cannot readily
645 reproduce or if you are modifying Pluto.
647 <P>Here are the Pluto developer's suggestions for doing this:
649 <PRE>Can you get a core dump and use gdb to find out what Pluto was doing
652 To get a core dump, you will have to set dumpdir to point to a
653 suitable directory (see <A HREF="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</A>).
655 To get gdb to tell you interesting stuff:
657 $ cd dump-directory-you-chose
658 $ gdb /usr/local/lib/ipsec/pluto core
663 The resulting output will have been captured by the script command in
664 a file called "typescript". Send it to the list.
666 Do not delete the core file. I may need to ask you to print out some
667 more relevant stuff.</PRE><P>
668 Note that the <VAR>dumpdir</VAR> parameter takes effect only when the
669 IPsec subsystem is restarted -- reboot or ipsec setup restart.</P>