1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
4 <TITLE>Introduction to FreeS/WAN
</TITLE>
5 <META HTTP-EQUIV=
"Content-Type" CONTENT=
"text/html; CHARSET=iso-8859-1">
6 <STYLE TYPE=
"text/css"><!--
7 BODY { font-family: serif }
8 H1 { font-family: sans-serif }
9 H2 { font-family: sans-serif }
10 H3 { font-family: sans-serif }
11 H4 { font-family: sans-serif }
12 H5 { font-family: sans-serif }
13 H6 { font-family: sans-serif }
14 SUB { font-size: smaller }
15 SUP { font-size: smaller }
16 PRE { font-family: monospace }
20 <A HREF=
"toc.html">Contents
</A>
21 <A HREF=
"firewall.html">Previous
</A>
22 <A HREF=
"compat.html">Next
</A>
24 <H1><A NAME=
"trouble"></A>Linux FreeS/WAN Troubleshooting Guide
</H1>
25 <H2><A NAME=
"overview"></A>Overview
</H2>
26 <P> This document covers several general places where you might have a
29 <LI><A HREF=
"#install">During install
</A>.
</LI>
30 <LI><A HREF=
"#negotiation">During the negotiation process
</A>.
</LI>
31 <LI><A HREF=
"#use">Using an established connection
</A>.
</LI>
33 <P>This document also contains
<A HREF=
"#notes"> notes
</A> which expand
34 on points made in these sections, and tips for
<A HREF=
"#prob.report">
35 problem reporting
</A>. If the other end of your connection is not
36 FreeS/WAN, you'll also want to read our
<A HREF=
"interop.html#interop.problem">
37 interoperation
</A> document.
</P>
38 <H2><A NAME=
"install"></A>1. During Install
</H2>
39 <H3><A NAME=
"8_2_1">1.1 RPM install gotchas
</A></H3>
40 <P>With the RPM method:
</P>
42 <LI>Be sure you have installed both the userland tools and the kernel
43 components. One will not work without the other. For example, when
44 using FreeS/WAN-produced RPMs for our
2.04 release, you need both:
45 <PRE> freeswan-userland-
2.04_2.4
.20_20.9-
0.i386.rpm
46 freeswan-module-
2.04_2.4
.20_20.9-
0.i386.rpm
50 <H3><A NAME=
"8_2_2">1.2 Problems installing from source
</A></H3>
51 <P>When installing from source, you may find these problems:
</P>
53 <LI>Missing library. See
<A HREF=
"faq.html#gmp.h_missing"> this
</A> FAQ.
</LI>
54 <LI>Missing utilities required for compile. See this
<A HREF=
"install.html#tool.lib">
56 <LI>Kernel version incompatibility. See
<A HREF=
"faq.html#k.versions">
58 <LI>Another compile problem. Find information in the out.* files, ie.
59 out.kpatch, out.kbuild, created at compile time in the top-level Linux
60 FreeS/WAN directory. Error messages generated by KLIPS during the boot
61 sequence are accessible with the
<VAR> dmesg
</VAR> command.
62 <BR> Check the list archives and the List in Brief to see if this is a
63 known issue. If it is not, report it to the bugs list as described in
64 our
<A HREF=
"#prob.report"> problem reporting
</A> section. In some
65 cases, you may be asked to provide debugging information using gdb;
66 details
<A HREF=
"#gdb"> below
</A>.
</LI>
67 <LI>If your kernel compiles but you fail to install your new
68 FreeS/WAN-enabled kernel, review the sections on
<A HREF=
"install.html#newk">
69 installing the patched kernel
</A>, and
<A HREF=
"install.html#testinstall">
70 testing
</A> to see if install succeeded.
</LI>
72 <H3><A NAME=
"install.check"></A>1.3 Install checks
</H3>
73 <P><VAR>ipsec verify
</VAR> checks a number of FreeS/WAN essentials. Here
74 are some hints on what do to when your system doesn't check out:
</P>
77 <TR><TD><STRONG>Problem
</STRONG></TD><TD><STRONG>Status
</STRONG></TD><TD>
78 <STRONG>Action
</STRONG></TD></TR>
79 <TR><TD><VAR>ipsec
</VAR> not on-path
</TD><TD> </TD><TD>
80 <P>Add
<VAR> /usr/local/sbin
</VAR> to your PATH.
</P>
82 <TR><TD>Missing KLIPS support
</TD><TD><FONT COLOR=
"#FF0000">critical
</FONT>
83 </TD><TD>See
<A HREF=
"faq.html#noKLIPS"> this FAQ.
</A></TD></TR>
84 <TR><TD>No RSA private key
</TD><TD> </TD><TD>
85 <P>Follow
<A HREF=
"install.html#genrsakey"> these instructions
</A> to
86 create an RSA key pair for your host. RSA keys are:
</P>
88 <LI>required for opportunistic encryption, and
</LI>
89 <LI>our preferred method to authenticate pre-configured connections.
</LI>
92 <TR><TD><VAR>pluto
</VAR> not running
</TD><TD><FONT COLOR=
"#FF0000">
93 critical
</FONT></TD><TD>
94 <PRE>service ipsec start
</PRE>
96 <TR><TD>No port
500 hole
</TD><TD><FONT COLOR=
"#FF0000">critical
</FONT></TD><TD>
97 Open port
500 for IKE negotiation.
</TD></TR>
98 <TR><TD>Port
500 check N/A
</TD><TD> </TD><TD>Check that port
500 is open
99 for IKE negotiation.
</TD></TR>
100 <TR><TD>Failed DNS checks
</TD><TD> </TD><TD>Opportunistic encryption
101 requires information from DNS. To set this up, see
<A HREF=
"quickstart.html#opp.setup">
102 our instructions
</A>.
</TD></TR>
103 <TR><TD>No public IP address
</TD><TD> </TD><TD>Check that the interface
104 which you want to protect with IPSec is up and running.
</TD></TR>
106 <H3><A NAME=
"oe.trouble"></A>1.3 Troubleshooting OE
</H3>
107 <P>OE should work with no local configuration, if you have posted DNS
108 TXT records according to the instructions in our
<A HREF=
"quickstart.html">
109 quickstart guide
</A>. If you encounter trouble, try these hints. We
110 welcome additional hints via the
<A HREF=
"mail.html"> users' mailing
113 <TR><TD><STRONG>Symptom
</STRONG></TD><TD><STRONG>Problem
</STRONG></TD><TD>
114 <STRONG>Action
</STRONG></TD></TR>
115 <TR><TD> You're running FreeS/WAN
2.01 (or later), and initiating a
116 connection to FreeS/WAN
2.00 (or earlier). In your logs, you see a
118 <PRE>no RSA public key known for '
192.0.2.13';
119 DNS search for KEY failed (no KEY record
120 for
13.2.0.192.in-addr.arpa.)
</PRE>
121 The older FreeS/WAN logs no error.
</TD><TD><A NAME=
"oe.trouble.flagday">
122 </A> A protocol level incompatibility between
2.01 (or later) and
2.00
123 (or earlier) causes this error. It occurs when a FreeS/WAN
2.01 (or
124 later) box for which no KEY record is posted attempts to initiate an OE
125 connection to older FreeS/WAN versions (
2.00 and earlier). Note that
126 older versions can initiate to newer versions without this error.
</TD><TD>
127 If you control the peer host, upgrade its FreeS/WAN to
2.01 (or later),
128 and post new style TXT records for it. If not, but if you know its
129 sysadmin, perhaps a quick note is in order. If neither option is
130 possible, you can ease the transition by posting an old style KEY
131 record (created with a command like
"ipsec
showhostkey
--key
") to the
132 reverse map for the FreeS/WAN
2.01 (or later) box.
</TD></TR>
133 <TR><TD>OE host is very slow to contact other hosts.
</TD><TD>Slow DNS
134 service while running OE.
</TD><TD>It's a good idea to run a caching DNS
135 server on your OE host, as outlined in
<A HREF=
"http://lists.freeswan.org/pipermail/design/2003-January/004205.html">
136 this mailing list message
</A>. If your DNS servers are elsewhere, put
137 their IPs in the
<VAR> clear
</VAR> policy group, and re-read groups with
138 <PRE>ipsec auto --rereadgroups
</PRE>
141 <PRE>Can't Opportunistically initiate for
142 192.0.2.2 to
192.0.2.3: no TXT record
143 for
13.2.0.192.in-addr.arpa.
</PRE>
144 </TD><TD>Peer is not set up for OE.
</TD><TD>
145 <P>None. Plenty of hosts on the Internet do not run OE. If, however, you
146 have set OE up on that peer, this may indicate that you need to wait up
147 to
48 hours for its DNS records to propagate.
</P>
149 <TR><TD><VAR>ipsec verify
</VAR> does not find DNS records:
151 Looking for TXT in forward map:
152 xy.example.com...[FAILED]
153 Looking for TXT in reverse map...[FAILED]
155 You also experience authentication failure:
157 <PRE>Possible authentication failure:
158 no acceptable response to our
159 first encrypted message
</PRE>
160 </TD><TD>DNS records are not posted or have not propagated.
</TD><TD>Did
161 you post the DNS records necessary for OE? If not, do so using the
162 instructions in our
<A HREF=
"quickstart.html#quickstart"> quickstart
163 guide
</A>. If so, wait up to
48 hours for the DNS records to propagate.
</TD>
165 <TR><TD><VAR>ipsec verify
</VAR> does not find DNS records, and you
166 experience authentication failure.
</TD><TD>For iOE, your ID does not
167 match location of forward DNS record.
</TD><TD>In
<VAR> config setup
</VAR>
168 , change
<VAR> myid=
</VAR> to match the forward DNS where you posted the
169 record. Restart FreeS/WAN. For reference, see our
<A HREF=
"quickstart.html#opp.client">
170 iOE instructions
</A>.
</TD></TR>
171 <TR><TD><VAR>ipsec verify
</VAR> finds DNS records, yet there is still
172 authentication failure. ( ? )
</TD><TD>DNS records are malformed.
</TD><TD>
173 Re-create the records and send new copies to your DNS administrator.
</TD>
175 <TR><TD><VAR>ipsec verify
</VAR> finds DNS records, yet there is still
176 authentication failure. ( ? )
</TD><TD>DNS records show different keys
177 for a gateway vs. its subnet hosts.
</TD><TD>All TXT records for boxes
178 protected by an OE gateway must contain the gateway's public key.
179 Re-create and re-post any incorrect records using
<A HREF=
"quickstart.html#opp.incoming">
180 these instructions
</A>.
</TD></TR>
181 <TR><TD>OE gateway loses connectivity to its subnet. The gateway's
182 routing table shows routes to the subnet through IPsec interfaces.
</TD><TD>
183 The subnet is part of the
<VAR> private
</VAR> or
<VAR> block
</VAR> policy
184 group on the gateway.
</TD><TD>Remove the subnet from the group, and
186 <PRE>ipsec auto --rereadgroups
</PRE>
188 <TR><TD>OE does not work to hosts on the local LAN.
</TD><TD>This is a
189 known issue.
</TD><TD>See
<A HREF=
"opportunism.known-issues"> this list
</A>
190 of known issues with OE.
</TD></TR>
191 <TR><TD>FreeS/WAN does not seem to be executing your default policy. In
192 your logs, you see a message like:
193 <PRE>/etc/ipsec.d/policies/iprivate-or-clear
"
194 line
14: subnet
"0.0.0.0/
0",
195 source
192.0.2.13/
32,
196 already
"private-or-clear
"</PRE>
197 </TD><TD><A HREF=
"glossary.html#fullnet">Fullnet
</A> in a policy group
198 file defines your default policy. Fullnet should normally be present in
199 only one policy group file. The fine print: you can have two default
200 policies defined so long as they protect different local endpoints
201 (e.g. the FreeS/WAN gateway and a subnet).
</TD><TD> Find all policies
202 which contain fullnet with:
204 <PRE>grep -F
0.0.0.0/
0 /etc/ipsec.d/policies/*
</PRE>
205 then remove the unwanted occurrence(s).
</TD></TR>
207 <H2><A NAME=
"negotiation"></A>2. During Negotiation
</H2>
208 <P>When you fail to bring up a tunnel, you'll need to find out:
</P>
210 <LI><A HREF=
"#state">what your connection state is,
</A> and often
</LI>
211 <LI><A HREF=
"#find.pluto.error">an error message
</A>.
</LI>
213 <P>before you can
<A HREF=
"#interpret.pluto.error"> diagnose your problem
</A>
215 <H3><A NAME=
"state"></A>2.1 Determine Connection State
</H3>
216 <H4>Finding current state
</H4>
217 <P>You can see connection states (STATE_MAIN_I1 and so on) when you
218 bring up a connection on the command line. If you have missed this, or
219 brought up your connection automatically, use:
</P>
220 <PRE>ipsec auto --status
</PRE>
221 <P>The most relevant state is the last one reached.
</P>
222 <H4><VAR>What's this supposed to look like?
</VAR></H4>
223 <P>Negotiations should proceed though various states, in the processes
226 <LI>IKE negotiations (aka Phase
1, Main Mode, STATE_MAIN_*)
</LI>
227 <LI>IPSEC negotiations (aka Phase
2, Quick Mode, STATE_QUICK_*)
</LI>
229 <P>These are done and a connection is established when you see messages
231 <PRE> 000 #
21:
"myconn
" STATE_MAIN_I4 (ISAKMP SA established)...
232 000 #
2:
"myconn
" STATE_QUICK_I2 (sent QI2, IPsec SA established)...
</PRE>
233 <P> Look for the key phrases are
"ISAKMP SA established
" and
"IPSec SA
234 established
", with the relevant connection name. Often, this happens at
235 STATE_MAIN_I4 and STATE_QUICK_I2, respectively.
</P>
236 <P><VAR>ipsec auto --status
</VAR> will tell you what states
<STRONG> have
237 been achieved
</STRONG>, rather than the current state. Since
238 determining the current state is rather more difficult to do, current
239 state information is not available from Linux FreeS/WAN. If you are
240 actively bringing a connection up, the status report's last states for
241 that connection likely reflect its current state. Beware, though, of
242 the case where a connection was correctly brought up but is now downed:
243 Linux FreeS/WAN will not notice this until it attempts to rekey.
244 Meanwhile, the last known state indicates that the connection has been
246 <P>If your connection is stuck at STATE_MAIN_I1, skip straight to
<A HREF=
"#ikepath">
248 <H3><A NAME=
"find.pluto.error"></A>2.2 Finding error text
</H3>
249 <P>Solving most errors will require you to find verbose error text,
250 either on the command line or in the logs.
</P>
251 <H4>Verbose start for more information
</H4>
252 <P> Note that you can get more detail from
<VAR> ipsec auto
</VAR> using
253 the --verbose flag:
</P>
254 <PRE STYLE=
"margin-bottom: 0.2in"> ipsec auto --verbose --up west-east
</PRE>
255 <P> More complete information can be gleaned from the
<A HREF=
"#logusage">
257 <H4>Debug levels count
</H4>
258 <P>The amount of description you'll get here depends on ipsec.conf debug
259 settings,
<VAR> klipsdebug
</VAR>= and
<VAR> plutodebug
</VAR>=. When
260 troubleshooting, set at least one of these to
<VAR> all
</VAR>, and when
261 done, reset it to
<VAR> none
</VAR> so your logs don't fill up. Note that
262 you must have enabled the
<VAR> klipsdebug
</VAR><A HREF=
"install.html#allbut">
263 compile-time option
</A> for the
<VAR> klipsdebug
</VAR> configuration
265 <P>For negotiation problems
<VAR> plutodebug
</VAR> is most relevant.
<VAR>
266 klipsdebug
</VAR> applies mainly to attempts to use an
267 already-established connection. See also
<A HREF=
"ipsec.html#parts">
268 this
</A> description of the division of duties within Linux FreeS/WAN.
</P>
269 <P>After raising your debug levels, restart Linux FreeS/WAN to ensure
270 that ipsec.conf is reread, then recreate the error to generate verbose
272 <H4><VAR>ipsec barf
</VAR> for lots of debugging information
</H4>
273 <P><A HREF=
"manpage.d/ipsec_barf.8.html"><VAR> ipsec barf (
8)
</VAR></A>
274 collects a bunch of useful debugging information, including these logs
277 ipsec barf
> barf.west
279 <P>to generate one.
</P>
280 <H4>Find the error
</H4>
281 <P>Search out the failure point in your logs. Are there a handful of
282 lines which succinctly describe how things are going wrong or contrary
283 to your expectation? Sometimes the failure point is not immediately
284 obvious: Linux FreeS/WAN's errors are usually not marked
"Error
". Have
285 a look in the
<A HREF=
"faq.html"> FAQ
</A> for what some common failures
287 <P>Tip: problems snowball. Focus your efforts on the first problem,
288 which is likely to be the cause of later errors.
</P>
289 <H4>Play both sides
</H4>
290 <P>Also find error text on the peer IPSec box. This gives you two
291 perspectives on the same failure.
</P>
292 <P>At times you will require information which only one side has. The
293 peer can merely indicate the presence of an error, and its approximate
294 point in the negotiations. If one side keeps retrying, it may be
295 because there is a show stopper on the other side. Have a look at the
296 other side and figure out what it doesn't like.
</P>
297 <P>If the other end is not Linux FreeS/WAN, the principle is the same:
298 replicate the error with its most verbose logging on, and capture the
299 output to a file.
</P>
300 <H3><A NAME=
"interpret.pluto.error"></A>2.3 Interpreting a Negotiation
302 <H4><A NAME=
"ikepath"></A>Connection stuck at STATE_MAIN_I1
</H4>
303 <P>This error commonly happens because IKE (port
500) packets, needed to
304 negotiate an IPSec connection, cannot travel freely between your IPSec
305 gateways. See
<A HREF=
"firewall.html#packets"> our firewall document
</A>
307 <H4>Other errors
</H4>
308 <P>Other errors require a bit more digging. Use the following resources:
</P>
310 <LI><A HREF=
"faq.html">the FAQ
</A> . Since this document is constantly
311 updated, the snapshot's FAQ may have a new entry relevant to your
313 <LI>our
<A HREF=
"background.html"> background document
</A> . Special
314 considerations which, while not central to Linux FreeS/WAN, are often
315 tripped over. Includes problems with
<A href=
"background.html#MTU.trouble">
316 packet fragmentation
</A>, and considerations for testing opportunism.
</LI>
317 <LI>the
<A HREF=
"mail.html#lists"> list archives
</A>. Each of the
318 searchable archives works differently, so it's worth checking each. Use
319 a search term which is generic, but identifies your error, for example
320 "No connection is known for
".
321 <BR> Often, you will find that your question has been answered in the
322 past. Finding an archived answer is quicker than asking the list. You
323 may, however, find similar questions without answers. If you do, send
324 their URLs to the list with your trouble report. The additional
325 examples may help the list tech support person find your answer.
</LI>
326 <LI>Look into the code where the error is being generated. The pluto
327 code is nicely documented with comments and meaningful variable names.
</LI>
329 <P>If you have failed to solve your problem with the help of these
330 resources, send a detailed problem report to the users list, following
331 these
<A HREF=
"#prob.report"> guidelines
</A>.
</P>
332 <H2><A NAME=
"use"></A>3. Using a Connection
</H2>
333 <H3><A NAME=
"8_4_1">3.1 Orienting yourself
</A></H3>
334 <H4><VAR>How do I know if it works?
</VAR></H4>
335 <P>Test your connection by sending packets through it. The simplest way
336 to do this is with ping, but the ping needs to
<STRONG> test the correct
337 tunnel.
</STRONG> See
<A HREF=
"#testgates"> this example scenario
</A> if
338 you don't understand this.
</P>
340 <P>If your ping returns, test any other connections you've brought u all
341 check out, great. You may wish to
<A HREF=
"#bigpacket"> test with large
342 packets
</A> for MTU problems.
</P>
343 <H4><VAR>ipsec barf
</VAR> is useful again
</H4>
344 <P>If your ping fails to return, generate an ipsec barf debugging report
345 on each IPSec gateway. On a non-Linux FreeS/WAN implementation, gather
346 equivalent information. Use this, and the tips in the next sections, to
347 troubleshoot. Are you sure that both endpoints are capable of hearing
348 and responding to ping?
</P>
349 <H3><A NAME=
"8_4_2">3.2 Those pesky configuration errors
</A></H3>
350 <P>IPSec may be dropping your ping packets since they do not belong in
351 the tunnels you have constructed:
</P>
353 <LI>Your ping may not test the tunnel you intend to test. For details,
354 see our
<A HREF=
"faq.html#cantping"> "I can't ping
"</A> FAQ.
</LI>
355 <LI> Alternately, you may have a configuration error. For example, you
356 may have configured one of the four possible tunnels between two
357 gateways, but not the one required to secure the important traffic
358 you're now testing. In this case, add and start the tunnel, and try
361 <P>In either case, you will often see a message like:
</P>
362 <PRE>klipsdebug... no eroute
</PRE>
363 <P>which we discuss in
<A HREF=
"faq.html#no_eroute"> this FAQ
</A>.
</P>
366 <LI><A HREF=
"glossary.html#NAT.gloss">Network Address Translation (NAT)
</A>
367 and
<A HREF=
"glossary.html#masq"> IP masquerade
</A> may have an effect
368 on which tunnels you need to configure.
</LI>
369 <LI>When testing a tunnel that protects a multi-node subnet, try several
370 subnet nodes as ping targets, in case one node is routing incorrectly.
</LI>
372 <H3><A NAME=
"route.firewall"></A>3.3 Check Routing and Firewalling
</H3>
373 <P>If you've confirmed your configuration assumptions, the problem is
374 almost certainly with routing or firewalling. Isolate the problem using
375 interface statistics, firewall statistics, or a packet sniffer.
</P>
378 <LI>Linux FreeS/WAN supplies all the special routing it needs; you need
379 only route packets out through your IPSec gateway. Verify that on the
<VAR>
380 subnetted
</VAR> machines you are using for your ping-test, your routing
381 is as expected. I have seen a tunnel
"fail
" because the subnet machine
382 sending packets out an alternate gateway (not our IPSec gateway) on
383 their return path.
</LI>
384 <LI>Linux FreeS/WAN requires particular
<A HREF=
"firewall.html">
385 firewalling considerations
</A>. Check the firewall rules on your IPSec
386 gateways and ensure that they allow IPSec traffic through. Be sure that
387 no other machine - for example a router between the gateways - is
388 blocking your IPSec packets.
</LI>
390 <H4><A NAME=
"ifconfig"></A>View Interface and Firewall Statistics
</H4>
391 <P>Interface reports and firewall statistics can help you track down
392 lost packets at a glance. Check any firewall statistics you may be
393 keeping on your IPSec gateways, for dropped packets.
</P>
394 <P><STRONG>Tip
</STRONG>: You can take a snapshot of the packets
395 processed by your firewall with:
</P>
396 <PRE> iptables -L -n -v
</PRE>
397 <P>You can get creative with
"diff
" to find out what happens to a
398 particular packet during transmission.
</P>
399 <P>Both
<VAR> cat /proc/net/dev
</VAR> and
<VAR> ifconfig
</VAR> display
400 interface statistics, and both are included in
<VAR> ipsec barf
</VAR>.
401 Use either to check if any interface has dropped packets. If you find
402 that one has, test whether this is related to your ping. While you ping
403 continuously, print that interface's statistics several times. Does its
404 drop count increase in proportion to the ping? If so, check why the
405 packets are dropped there.
</P>
406 <P>To do this, look at the firewall rules that apply to that interface.
407 If the interface is an IPSec interface, more information may be
408 available in the log. Grep for the word
"drop
" in a log which was
409 created with
<VAR> klipsdebug=all
</VAR> as the error happened.
</P>
410 <P>See also this
<A HREF=
"#ifconfig1"> discussion
</A> on interpreting
<VAR>
411 ifconfig
</VAR> statistics.
</P>
412 <H3><A NAME=
"sniff"></A>3.4 When in doubt, sniff it out
</H3>
413 <P>If you have checked configuration assumptions, routing, and firewall
414 rules, and your interface statistics yield no clue, it remains for you
415 to investigate the mystery of the lost packet by the most thorough
416 method: with a packet sniffer (providing, of course, that this is legal
417 where you are working).
</P>
418 <P>In order to detect packets on the ipsec virtual interfaces, you will
419 need an up-to-date sniffer (tcpdump, ethereal, ksnuffle) on your IPSec
420 gateway machines. You may also find it useful to sniff the ping
422 <H4>Anticipate your packets' path
</H4>
423 <P>Ping, and examine each interface along the projected path, checking
424 for your ping's arrival. If it doesn't get to the the next stop, you
425 have narrowed down where to look for it. In this way, you can isolate a
426 problem area, and narrow your troubleshooting focus.
</P>
427 <P>Within a machine running Linux FreeS/WAN, this
<A HREF=
"firewall.html#packets">
428 packet flow diagram
</A> will help you anticipate a packet's path.
</P>
431 <LI> from the perspective of the tunneled packet, the entire tunnel is
432 one hop. That's explained in
<A HREF=
"faq.html#no_trace"> this
</A> FAQ.
</LI>
433 <LI> an encapsulated IPSec packet will look different, when sniffed,
434 from the plaintext packet which generated it. You can see plaintext
435 packets entering an IPSec interface and the resulting cyphertext
436 packets as they emerge from the corresponding physical interface.
</LI>
438 <P>Once you isolate where the packet is lost, take a closer look at
439 firewall rules, routing and configuration assumptions as they affect
440 that specific area. If the packet is lost on an IPSec gateway, comb
441 through
<VAR> klipsdebug
</VAR> output for anomalies.
</P>
442 <P>If the packet goes through both gateways successfully and reaches the
443 ping target, but does not return, suspect routing. Check that the ping
444 target routes packets back to the IPSec gateway.
</P>
445 <H3><A NAME=
"find.use.error"></A>3.5 Check your logs
</H3>
446 <P>Here, too, log information can be useful. Start with the
<A HREF=
"#find.pluto.error">
447 guidelines above
</A>.
</P>
448 <P>For connection use problems, set
<VAR> klipsdebug=all
</VAR>. Note that
449 you must have enabled the
<VAR> klipsdebug
</VAR><A HREF=
"install.html#allbut">
450 compile-time option
</A> to do this. Restart Linux FreeS/WAN so that it
451 rereads
<VAR> ipsec.conf
</VAR>, then recreate the error condition. When
452 searching through
<VAR> klipsdebug
</VAR> data, look especially for the
453 keywords
"drop
" (as in dropped packets) and
"error
".
</P>
454 <P>Often the problem with connection use is not software error, but
455 rather that the software is behaving contrary to expectation.
</P>
456 <H4><A NAME=
"interpret.use.error"></A>Interpreting log text
</H4>
457 <P>To interpret the Linux FreeS/WAN log text you've found, use the same
458 resources as indicated for troubleshooting connection negotiation:
<A HREF=
"faq.html">
459 the FAQ
</A> , our
<A HREF=
"background.html"> background document
</A>,
460 and the
<A HREF=
"mail.html#lists"> list archives
</A>. Looking in the
461 KLIPS code is only for the very brave.
</P>
462 <P>If you are still stuck, send a
<A HREF=
"#prob.report"> detailed
463 problem report
</A> to the users' list.
</P>
464 <H3><A NAME=
"bigpacket"></A>3.6 More testing for the truly thorough
</H3>
465 <H4>Large Packets
</H4>
466 <P>If each of your connections passed the ping test, you may wish to
467 test by pinging with large packets (
2000 bytes or larger). If it does
468 not return, suspect MTU issues, and see this
<A HREF=
"background.html#MTU.trouble">
470 <H4>Stress Tests
</H4>
471 <P>In most users' view, a simple ping test, and perhaps a large-packet
472 ping test suffice to indicate a working IPSec connection.
</P>
473 <P>Some people might like to do additional stress tests prior to
474 production use. They may be interested in this
<A HREF=
"http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/12/msg00224.html">
475 testing protocol
</A> we use at interoperation conferences, aka
476 "bakeoffs
". We also have a
<VAR> testing
</VAR> directory that ships with
478 <H2><A NAME=
"prob.report"></A>4. Problem Reporting
</H2>
479 <H3><A NAME=
"8_5_1">4.1 How to ask for help
</A></H3>
480 <P>Ask for troubleshooting help on the users' mailing list,
<A HREF=
"mailto:users@lists.freeswan.org">
481 users@lists.freeswan.org
</A>. While sometimes an initial query with a
482 quick description of your intent and error will twig someone's memory
483 of a similar problem, it's often necessary to send a second mail with a
484 complete problem report.
</P>
485 <P>When reporting problems to the mailing list(s), please include:
</P>
487 <LI>a brief description of the problem
</LI>
488 <LI>if it's a compile problem, the actual output from make, showing the
489 problem. Try to edit it down to only the relevant part, but when in
490 doubt, be as complete as you can. If it's a kernel compile problem, any
491 relevant out.* files
</LI>
492 <LI>if it's a run-time problem, pointers to where we can find the
493 complete output from
"ipsec barf
" from BOTH ENDS (not just one of
494 them). Remember that it's common outside the US and Canada to pay for
495 download volume, so if you can't post barfs on the web and send the URL
496 to the mailing list, at least compress them with tar or gzip.
497 <BR> If you can, try to simplify the case that is causing the problem.
498 In particular, if you clear your logs, start FreeS/WAN with no other
499 connections running, cause the problem to happen, and then do
<VAR>
500 ipsec barf
</VAR> on both ends immediately, that gives the smallest and
501 least cluttered output.
</LI>
502 <LI>any other error messages, complaints, etc. that you saw. Please send
503 the complete text of the messages, not just a summary.
</LI>
504 <LI>what your network setup is. Include subnets, gateway addresses, etc.
505 A schematic diagram is a good format for this information.
</LI>
506 <LI>exactly what you were trying to do with Linux FreeS/WAN, and exactly
508 <LI>a fix, if you have one. But remember, you are sending mail to people
509 all over the world; US residents and US citizens in particular, please
510 read doc/exportlaws.html before sending code -- even small bug fixes --
511 to the list or to us.
</LI>
512 <LI>When in doubt about whether to include some seemingly-trivial item
513 of information, include it. It is rare for problem reports to have too
514 much information, and common for them to have too little.
</LI>
516 <P>Here are some good general guidelines on bug reporting:
<A href=
"http://tuxedo.org/~esr/faqs/smart-questions.html">
517 How To Ask Questions The Smart Way
</A> and
<A href=
"http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">
518 How to Report Bugs Effectively
</A>.
</P>
519 <H3><A NAME=
"8_5_2">4.2 Where to ask
</A></H3>
520 <P>To report a problem, send mail about it to the users' list. If you
521 are certain that you have found a bug, report it to the bugs list. If
522 you encounter a problem while doing your own coding on the Linux
523 FreeS/WAN codebase and think it is of interest to the design team,
524 notify the design list. When in doubt, default to the users' list. More
525 information about the mailing lists is found
<A HREF=
"mail.html#lists">
527 <P>For a number of reasons -- including export-control regulations
528 affecting almost any
<STRONG> private
</STRONG> discussion of encryption
529 software -- we prefer that problem reports and discussions go to the
530 lists, not directly to the team. Beware that the list goes worldwide;
531 US citizens, read this important information about your
<A HREF=
"politics.html#exlaw">
532 export laws
</A>. If you're using this software, you really should be on
533 the lists. To get onto them, visit
<A HREF=
"http://lists.freeswan.org/">
534 lists.freeswan.org
</A>.
</P>
535 <P>If you do send private mail to our coders or want a private reply
536 from them, please make sure that the return address on your mail (From
537 or Reply-To header) is a valid one. They have more important things to
538 do than to unravel addresses that have been mangled in an attempt to
539 confuse spammers.
</P>
540 <H2><A NAME=
"notes"></A>5. Additional Notes on Troubleshooting
</H2>
541 <P>The following sections supplement the Guide:
<A HREF=
"#system.info">
542 information available on your system
</A>;
<A HREF=
"#testgates"> testing
543 between security gateways
</A>;
<A HREF=
"#ifconfig1"> ifconfig reports
544 for KLIPS debugging
</A>;
<A HREF=
"#gdb"> using GDB on Pluto
</A>.
</P>
545 <H3><A NAME=
"system.info"></A>5.1 Information available on your system
</H3>
546 <H4><A NAME=
"logusage"></A>Logs used
</H4>
547 <P>Linux FreeS/WAN logs to:
</P>
549 <LI>/var/log/secure (or, on Debian, /var/log/auth.log)
</LI>
550 <LI>/var/log/messages
</LI>
552 <P>Check both places to get full information. If you find nothing, check
553 your
<VAR> syslogd.conf(
5)
</VAR> to see where your /etc/syslog.conf or
554 equivalent is directing
<VAR> authpriv
</VAR> messages.
</P>
555 <H4><A NAME=
"pages"></A>man pages provided
</H4>
557 <DT><A HREF=
"manpage.d/ipsec.conf.5.html">ipsec.conf(
5)
</A></DT>
558 <DD> Manual page for IPSEC configuration file.
</DD>
559 <DT><A HREF=
"manpage.d/ipsec.8.html"> ipsec(
8)
</A></DT>
560 <DD STYLE=
"margin-bottom: 0.2in"> Primary man page for ipsec utilities.
</DD>
562 <P> Other man pages are on
<A HREF=
"manpages.html"> this list
</A> and in
</P>
564 <LI>/usr/local/man/man3
</LI>
565 <LI>/usr/local/man/man5
</LI>
566 <LI>/usr/local/man/man8/ipsec_*
</LI>
568 <H4><A NAME=
"statusinfo"></A>Status information
</H4>
570 <DT>ipsec auto --status
</DT>
571 <DD> Command to get status report from running system. Displays Pluto's
572 state. Includes the list of connections which are currently
"added
" to
573 Pluto's internal database; lists state objects reflecting ISAKMP and
574 IPsec SAs being negotiated or installed.
</DD>
576 <DD> Brief status info.
</DD>
578 <DD STYLE=
"margin-bottom: 0.2in"> Copious debugging info.
</DD>
580 <H3><A NAME=
"testgates"></A> 5.2 Testing between security gateways
</H3>
581 <P>Sometimes you need to test a subnet-subnet tunnel. This is a tunnel
582 between two security gateways, which protects traffic on behalf of the
583 subnets behind these gateways. On this network:
</P>
584 <PRE> Sunset==========West------------------East=========Sunrise
585 IPSec gateway IPSec gateway
586 local net untrusted net local net
</PRE>
587 <P> you might name this tunnel sunset-sunrise. You can test this tunnel
588 by having a machine behind one gateway ping a machine behind the other
589 gateway, but this is not always convenient or even possible.
</P>
590 <P>Simply pinging one gateway from the other is not useful. Such a ping
591 does not normally go through the tunnel.
<STRONG> The tunnel handles
592 traffic between the two protected subnets, not between the gateways
</STRONG>
593 . Depending on the routing in place, a ping might
</P>
595 <LI>either succeed by finding an unencrypted route
</LI>
596 <LI>or fail by finding no route. Packets without an IPSEC eroute are
599 <P><STRONG>Neither event tells you anything about the tunnel
</STRONG>.
600 You can explicitly create an eroute to force such packets through the
601 tunnel, or you can create additional tunnels as described in our
<A HREF=
"config.html#multitunnel">
602 configuration document
</A>, but those may be unnecessary complications
603 in your situation.
</P>
604 <P>The trick is to explicitly test between
<STRONG> both gateways'
605 private-side IP addresses
</STRONG>. Since the private-side interfaces
606 are on the protected subnets, the resulting packets do go via the
607 tunnel. Use either ping -I or traceroute -i, both of which allow you to
608 specify a source interface. (Note: unsupported on older Linuxes). The
609 same principles apply for a road warrior (or other) case where only one
610 end of your tunnel is a subnet.
</P>
611 <H3><A NAME=
"ifconfig1"></A>5.3 ifconfig reports for KLIPS debugging
</H3>
612 <P>When diagnosing problems using ifconfig statistics, you may wonder
613 what type of activity increments a particular counter for an ipsecN
614 device. Here's an index, posted by KLIPS developer Richard Guy Briggs:
</P>
615 <PRE>Here is a catalogue of the types of errors that can occur for which
616 statistics are kept when transmitting and receiving packets via klips.
617 I notice that they are not necessarily logged in the right counter.
620 Sources of ifconfig statistics for ipsec devices
623 - packet handed to ipsec_rcv that is not an ipsec packet.
624 - ipsec packet with payload length not modulo
4.
625 - ipsec packet with bad authenticator length.
626 - incoming packet with no SA.
628 - incoming authentication failed.
629 - got esp packet with length not modulo
8.
632 - cannot process ip_options.
633 - packet ttl expired.
634 - packet with no eroute.
636 - cannot allocate sk_buff.
637 - cannot allocate kernel memory.
638 - sk_buff internal error.
641 The standard counters are:
643 struct enet_statistics
645 int rx_packets; /* total packets received */
646 int tx_packets; /* total packets transmitted */
647 int rx_errors; /* bad packets received */
648 int tx_errors; /* packet transmit problems */
649 int rx_dropped; /* no space in linux buffers */
650 int tx_dropped; /* no space available in linux */
651 int multicast; /* multicast packets received */
654 /* detailed rx_errors: */
655 int rx_length_errors;
656 int rx_over_errors; /* receiver ring buff overflow */
657 int rx_crc_errors; /* recved pkt with crc error */
658 int rx_frame_errors; /* recv'd frame alignment error */
659 int rx_fifo_errors; /* recv'r fifo overrun */
660 int rx_missed_errors; /* receiver missed packet */
662 /* detailed tx_errors */
663 int tx_aborted_errors;
664 int tx_carrier_errors;
666 int tx_heartbeat_errors;
667 int tx_window_errors;
670 of which I think only the first
6 are useful.
</PRE>
671 <H3><A NAME=
"gdb"></A> 5.4 Using GDB on Pluto
</H3>
672 <P>You may need to use the GNU debugger, gdb(
1), on Pluto. This should
673 be necessary only in unusual cases, for example if you encounter a
674 problem which the Pluto developer cannot readily reproduce or if you
675 are modifying Pluto.
</P>
676 <P>Here are the Pluto developer's suggestions for doing this:
</P>
677 <PRE>Can you get a core dump and use gdb to find out what Pluto was doing
680 To get a core dump, you will have to set dumpdir to point to a
681 suitable directory (see
<A HREF=
"manpage.d/ipsec.conf.5.html">ipsec.conf(
5)
</A>).
683 To get gdb to tell you interesting stuff:
685 $ cd dump-directory-you-chose
686 $ gdb /usr/local/lib/ipsec/pluto core
691 The resulting output will have been captured by the script command in
692 a file called
"typescript
". Send it to the list.
694 Do not delete the core file. I may need to ask you to print out some
695 more relevant stuff.
</PRE>
696 <P> Note that the
<VAR> dumpdir
</VAR> parameter takes effect only when
697 the IPsec subsystem is restarted -- reboot or ipsec setup restart.
</P>
702 <A HREF=
"toc.html">Contents
</A>
703 <A HREF=
"firewall.html">Previous
</A>
704 <A HREF=
"compat.html">Next
</A>
projects / people / ms / strongswan.git / blob