Chapter 12

$ ps ax | grep gdb

1659 pts/9 SN 0:00 /usr/bin/gdb -fullname -cd /umls/umlbuild/east/ linux

Set the following in the environment:

$ UML_east_OPT="debug gdb-pid=1659"

Then start the UML in the test scheme you wish:

$ cd testing/klips/east-icmp-02 $ ../../utils/runme.sh

The UML will stop on boot, giving you a chance to attach to the process:

(gdb) file linux

Reading symbols from linux...done. (gdb) attach 1

Attaching to program: /mara4/openswan/kernpatch/UMLPOOL/swan/linux, process 1 0xa0118bc1 in kill () at hostfs_kern.c:770

At this point, break points should be created as appropriate. If you are running a standard test, after all the packets are sent, the UML will be shut down. This can cause problems, because the UML may get terminated while you are debugging. The environment variable NETJIGWAITUSER can be set to 'waituser'. If so, then the testing system will prompt before exiting the test.

Asking the Openswan Community for Help

There are various sources of information about Openswan available on the Internet. Apart from the documentation that comes with Openswan, there is an Openswan Wiki at http://wiki.openswan.org. Using a search engine or browsing the user mailing list archive can also be very helpful. Or you can try IRC.

Internet Relay Chat (IRC)

You can ask your question on the #openswan IRC channel on FreeNode (irc.freenode.net). When asking questions through IRC, do not ask for permission to ask a question, just ask it, even if people are idle for hours. Some of the developers are often lingering idly on the channel, and might not notice your question immediately. Ask your question and hang around for a while, and you will be surprised how helpful that can be. Many people who join the #openswan channel for the first time ask a question on IRC and leave within five minutes because they think no one is listening. Have some patience; most developers have a day job, and will not be able to respond in seconds.

The Openswan Mailing Lists

If you believe your issue is rather specific, then it is time to organize your information and ask for help on the Openswan mailing lists. There are currently four mailing lists for Openswan. For a complete overview, please see http://lists.openswan.org/.

301

Debugging and Troubleshooting

Openswan Mailing List	Description
announce	A very low volume announce-only mailing list. New versions and important
	information about security issues with other software is announced here.
users	Mailing list for system administrators trying to build and set up Openswan.
dev	Mailing list for developers and for reporting software bugs. This list is not meant
	for configuration issues. If you are unsure whether your issue is a configuration
	issue or a bug, please use the users list.
cvs	This is an announce-only mailing list of every code change in the CVS repository.
	This is useful for developers who want to closely track Openswan development,
	and those who have their own fork of our code.

If you are not subscribed to the list you are trying to send email to, your message will be held for the moderator to approve. This can take a few hours to a few days.

Posting to the Lists

Use a proper subject line describing the problem. A subject with "help" or "Openswan fails to work properly" will not get as much attention as "Openswan fails to rekey a roadwarrior connection" or "Openswan responds with 'no connection is known' message". Start your email

with a short description of your setup. If you are using some 'ASCII art', ensure it does not take up more than about 70 characters, so it does not wrap and break when someone hits 'Reply' to your message. Also be aware of 'flowed messages'. Some mail programs assume that for any line ending with a space, the next line should be appended, and wrapped according to the reader's screen size. This does not work well with ASCII art drawings. An example of a proper configuration overview would be:

+------		+
| RW		| 10.0.1.101 eth0
+--	+---	+

	|
	| 10.0.1.254 lan
+--	+---------	+
| NAT router |
+--	+---------	+
	| 193.111.228.42 wan
internet
	|
	| 193.110.157.131 eth1
+--	+------------	+
| VPN2 Openswan |
+--	+------------	+

10.0.2.2 eth1

|

10.0.2.0/24

If your situation is simple enough, you can probably display it horizontally as well.

Then give a very brief summary of the problem, and what you believe is the relevant log error. For example:

302

Chapter 12

The roadwarrior (RW) machine fails to connect to the VPN2 server, which displays the error:

Cannot respond to...........[insert]

Then provide a link to a website that contains the output of the ipsec barf command. Do not run this command before the problem has occurred. If possible, clean out the log files (and perhaps restart the syslog service) so that all old log entries that are no longer appropriate will not become part of your report. Right after the error occurred, run ipsec barf > rw-vpn2-barf.txt. Depending on your setup, this might take from a few seconds to up to a minute to complete.

Do not send barf files to the user mailing list, since they can be huge. Also do not send configuration problems to the developer mailing list, unless you are sure that you are bitten by a software bug. If your problem turns out to be a software bug, the developers will bounce it to the developer mailing list when responding to your message. Do not CC your message to both the dev and users lists.

Do not send barf output or core dumps to the lists!

Research First, Ask Later

It should be unnecessary to say this, but the bulk of the Openswan user mailing list still relates to a handful of common configuration mistakes, and people not taking the time to research properly before asking for help. Remember that the mailing list is a community effort. Demanding a quick answer, or informing the list that you will lose your job if you do not get it working before tomorrow, will not help you getting your issue resolved. You will have much more luck getting a quick answer if you properly provide a brief overview of your problem, the relevant error message, and a link to the bulk of your information gathered on a web page. Asking questions like, "Can someone help me get this working with Windows?", or "I cannot get this to work, please help" also will not get you much help. (Yes, these types of questions without any configuration or log message are unfortunately very common.)

Free, as in Beer

Support through IRC and the mailing lists is free. It is given as a courtesy. Please treat it as such. Do not ask 20 questions per day. If you need 20 questions, then you have not done enough research. Do not repeat your question every day if you did not receive an answer. Do not demand response times. Do not try to give the community a guilt trip about you losing your job if you cannot get this to work now. Do not email the people who answer to the mailing lists privately for more. The whole idea is that this free support is shared by the community. Various people can help you if you post to the list, and if the answer appears on the list, others will be able to find it when running into the same issue, reducing the workload for the developers who answer these questions.

Do not Anonymize

Obfuscating your information by replacing your (private and sensitive) IP addresses with letters is another good way of discouraging people from helping you. Without the proper information people cannot provide assistance. People are often willing to share information if you make it easy for them to do so. Providing them with an unreadable puzzle will not encourage them.

303