freeswan/doc/src/trouble.html

   1 <HTML>
   2 <HEAD>
   3         <TITLE>FreeS/WAN troubleshooting</TITLE>
   4       <meta name="keywords" content="Linux, IPSEC, VPN, security, FreeSWAN, troubleshooting, debugging">
   5 <!--
   6      Written by Claudia Schmeing for the Linux FreeS/WAN project
   7      Freely distributable under the GNU General Public License
   8
   9      More information at www.freeswan.org
  10      Feedback to users@lists.freeswan.org
  11
  12 CVS information:
  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 $
  16
  17 CVS revision numbers do not correspond to FreeS/WAN release numbers.
  18 -->
  19
  20 </HEAD>
  21 <BODY>
  22
  23 <H1><A NAME="guide"></A>Linux FreeS/WAN Troubleshooting Guide</H1>
  24
  25 <H2><A NAME="overview"></A>Overview</H2>
  26
  27 <P>
  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>
  31 <P>
  32 There are several general places where you might have a problem:</P>
  33 <OL>
  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>
  38 </OL>
  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>
  43 document.</P>
  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>
  47 <UL>
  48         <LI><P>Missing library. See <A HREF="faq.html#gmp.h_missing">this</A>
  49         FAQ.</P>
  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>
  52         FAQ.</P>
  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
  57         </P>
  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>
  67 </UL>
  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>
  80 <P>For example:</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
  86
  87 192.168.1.5                           N.N.N.235
  88
  89          eth0(external)=N.N.N.222
  90
  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
  96 name each tunnel?</P>
  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
 124 the command line:
 125 </P>
 126 <PRE STYLE="margin-bottom: 0.2in">    ipsec auto --add west-east</PRE><P>
 127 then</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 &quot;SA&quot;, loosely
 134 translated as &quot;tunnel&quot; or &quot;connection&quot;), 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:
 146 </P>
 147 <UL>
 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>.
 152         </P>
 153 </UL>
 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
 158 messages:</P>
 159 <PRE>    000 #21: &quot;myconn&quot; STATE_MAIN_I4 (ISAKMP SA established)...
 160     000 #2: &quot;myconn&quot; STATE_QUICK_I2 (sent QI2, IPsec SA established)...</PRE><P>
 161 The key phrases are &quot;ISAKMP SA established&quot; and &quot;IPSec
 162 SA established&quot;, 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
 180 process.</P>
 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
 188 files</A>.</P>
 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 &quot;none&quot; or &quot;all&quot;. 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
 196 work.</P>
 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
 203 verbose logs.
 204 </P>
 205 <P>
 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
 208 the command</P>
 209 <PRE>
 210     ipsec barf &gt; barf.west
 211 </PRE><P>
 212 See also the <A HREF="manpage.d/ipsec_barf.8.html">ipsec_barf(8)</A>
 213 man page.</P>
 214 <P>
 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 &quot;Error&quot;. 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
 233 it doesn't like.</P>
 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
 236 resources:</P>
 237 <UL>
 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
 240         to your problem.</P>
 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 &quot;No connection is known for&quot;.</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
 258         variable names.</P>
 259 </UL>
 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
 268 along that path.
 269 </P>
 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 &quot;think&quot;
 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>
 286 test the tunnel.
 287 </P>
 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 &quot;I can't ping&quot;. NAT and masquerading may
 295 have an effect on which tunnels you need to configure; that's
 296 discussed in &quot;<A HREF="#before">Before there's trouble</A>&quot;.</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 &quot;klipsdebug... no
 302 eroute&quot; message, which is discussed in <A HREF="faq.html#no_eroute">this
 303 FAQ</A>.
 304 </P>
 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>
 312 <P>Background:</P>
 313 <UL>
 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 &quot;fail&quot; 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
 325         packets.</P>
 326 </UL>
 327 <H4><A NAME="ifconfig"></A>4.2.1 View Interface and Firewall
 328 Statistics</H4>
 329 <P>Interface reports and firewall statistics can help you track down
 330 lost packets at a glance.
 331 </P>
 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 &quot;drop&quot; 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>
 367 FAQ.</P>
 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
 371 for it.
 372 </P>
 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
 377 physical interface.
 378 </P>
 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.
 383 </P>
 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 &quot;drop&quot; (as in dropped packets) and &quot;error&quot;.</P>
 395 <P>Often the problem with connection use is not software error, but
 396 rather that the software is behaving contrary to expectation.
 397 </P>
 398 <H4><A NAME="interpret.use.error"></A>4.4.1 Interpret a Connection
 399 Use Error</H4>
 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
 415 connection.</P>
 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 &quot;bakeoffs&quot;.
 419 We also have a <VAR>testing</VAR> directory that ships with the
 420 release.</P>
 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
 428 report.
 429 </P>
 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.
 432 </P>
 433 <P>When reporting problems to the mailing list(s), please include:
 434 </P>
 435 <UL>
 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 &quot;ipsec barf&quot; 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
 446         gzip.</P>
 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>
 466 </UL>
 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.
 487 </P>
 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
 494 system</H3>
 495 <H4><A NAME="logusage"></A>6.1.1 Logs used</H4>
 496 <P>Linux FreeS/WAN logs to:</P>
 497 <UL>
 498         <LI><P STYLE="margin-bottom: 0in">/var/log/secure (or, on Debian,
 499         /var/log/auth.log)
 500         </P>
 501         <LI><P>/var/log/messages
 502         </P>
 503 </UL>
 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>
 507 messages.</P>
 508 <H4><A NAME="pages"></A>6.1.2 man pages provided</H4>
 509 <DL>
 510         <DT><A HREF="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</A>
 511         </DT><DD>
 512         Manual page for IPSEC configuration file.
 513         </DD><DT>
 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.
 517         </DD></DL>
 518 <P>
 519 Other man pages are on <A HREF="manpages.html">this list</A> and in</P>
 520 <UL>
 521         <LI><P STYLE="margin-bottom: 0in">/usr/local/man/man3
 522         </P>
 523         <LI><P STYLE="margin-bottom: 0in">/usr/local/man/man5
 524         </P>
 525         <LI><P>/usr/local/man/man8/ipsec_*
 526         </P>
 527 </UL>
 528 <H4><A NAME="statusinfo"></A>6.1.3 Status information</H4>
 529 <DL>
 530         <DT>ipsec auto --status
 531         </DT><DD>
 532         Command to get status report from running system. Displays Pluto's
 533         state. Includes the list of connections which are currently &quot;added&quot;
 534         to Pluto's internal database; lists state objects reflecting ISAKMP
 535         and IPsec SAs being negotiated or installed.
 536         </DD><DT>
 537         ipsec look
 538         </DT><DD>
 539         Brief status info.
 540         </DD><DT>
 541         ipsec barf
 542         </DT><DD STYLE="margin-bottom: 0.2in">
 543         Copious debugging info.
 544         </DD></DL>
 545 <H3>
 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>
 560 <UL>
 561         <LI><P STYLE="margin-bottom: 0in">either succeed by finding an
 562         unencrypted route
 563         </P>
 564         <LI><P>or fail by finding no route. Packets without an IPSEC eroute
 565         are discarded.
 566         </P>
 567 </UL>
 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
 584 Briggs:</P>
 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.
 588 . . .
 589
 590 Sources of ifconfig statistics for ipsec devices
 591
 592 rx-errors:
 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.
 597 - replayed packet.
 598 - incoming authentication failed.
 599 - got esp packet with length not modulo 8.
 600
 601 tx_dropped:
 602 - cannot process ip_options.
 603 - packet ttl expired.
 604 - packet with no eroute.
 605 - eroute with no SA.
 606 - cannot allocate sk_buff.
 607 - cannot allocate kernel memory.
 608 - sk_buff internal error.
 609
 610
 611 The standard counters are:
 612
 613 struct enet_statistics
 614 {
 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 */
 622         int        collisions;
 623
 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 */
 631
 632         /* detailed tx_errors */
 633         int        tx_aborted_errors;
 634         int        tx_carrier_errors;
 635         int        tx_fifo_errors;
 636         int        tx_heartbeat_errors;
 637         int        tx_window_errors;
 638 };
 639
 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.
 646 </P>
 647 <P>Here are the Pluto developer's suggestions for doing this:
 648 </P>
 649 <PRE>Can you get a core dump and use gdb to find out what Pluto was doing
 650 when it died?
 651
 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>).
 654
 655 To get gdb to tell you interesting stuff:
 656         $ script
 657         $ cd dump-directory-you-chose
 658         $ gdb /usr/local/lib/ipsec/pluto core
 659         (gdb) where
 660         (gdb) quit
 661         $ exit
 662
 663 The resulting output will have been captured by the script command in
 664 a file called &quot;typescript&quot;.  Send it to the list.
 665
 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>
 670 <P><BR><BR>
 671 </P>
 672 </BODY>
 673 </HTML>