First and foremost, in order to debug part of Bongo effectively, you need a debug build. In general, packaged Bongo isn't suitable for this.
Compiling from source, I often start like this:
./autogen.sh --prefix=/tmp/bongo-build --enable-debug-cflags
You can set the build anywhere; I generally put testing builds in /tmp/ just because it's self-contained and I can install as my user - I don't need to be root. The cflags part is important, though - you need it to include the debugging information in the binaries. Without this, you'll find it impossible to debug them effectively.
Contents |
[edit] Debugging Agents
Agents are the simplest thing to debug. However, they do need "infrastructure" running - usually at least the Bongo store agent. If you need to debug the store, that can usually be run on its own.
The main way to debug an agent is to first start Bongo with bongo-manager in a terminal, on it's own, without allowing it to daemonize - that way, you will see any output messages. You probably also want to watch the syslog.
Once bongo-manager is running, you want to debug the agent. Start it in gdb, something like this:
gdb /tmp/bongo-build/sbin/bongosmtp `pgrep bongosmtp`
Mind the quotes: those are back-ticks, not apostrophes, and are located on the top-left of my keyboard. If in doubt, copy and paste the above command!
This will either attach to a running agent, or restart the agent if it wasn't already running. If it attaches, you want to 'c' to continue the agent running, otherwise 'r' to run the agent (start it from scratch).
gdb can be used to set breakpoints within the agent if there is a specific part you're trying to look into. If it's just a segfault you're tracking, try to trigger the crash, and then when gdb falls back to the command line you can do:
bt full
... to create a full picture of what was going on at the time of the crash. Developers will often ask for this when trying to debug a crash, it's called a "stack trace" or "back trace".
[edit] Various gdb tips
Ideally, you need to know how to drive gdb. But as a quick overview, you basically type in commands at the prompt to control the program:
- break name - set a breakpoint at function name()
- r - run the program
- n - run the next instruction / function
- s - run and step into the next instruction / function (if you're in a breakpoint)
- print var - output the value contained in var
- c - continue normal execution after a break
- bt - print the stack trace; very useful after a crash
[edit] Getting protocol traces
There are many network protocols used throughout Bongo. When diagnosing a client bug, it's usually useful to find out what is being said - both between the agent and the client, and the agent and the store.
You can do this easily with 'tcpick', which you should install if you haven't already. Set up two root shells, and find out what ports you want to sniff. To sniff conversations with the store you want port 689, smtp is 25, pop3 110 and imap 143.
The basic command to do the sniff is:
tcpick -i lo -C -yP -T1 "port 689"
... changing the number to sniff other ports. Usually, you want one sniffing the store port, and another tcpick sniffing smtp/imap/whatever.
Add the -wR option if you also want to save the content to a file - this is useful for sending other people copies of your traces.
When doing traces, try to have as little accessing Bongo as possible - preferably, nothing else other than your test - to prevent useless 'fluff' getting in the trace.
[edit] Installing tcpick on RPath
If asked to send a protocol trace to a developer you will need to install tcpick
login to the console of your appliance as root and issue the following commands
conary update libpcap=conary.rpath.com@rpl:1 conary update tcpick=bongo.rpath.org@rpl:devel
now ssh on to the appliance with 2 sessions as root
with the first session run the command
tcpick -i eth0 -C -yP -T1 -wR "port 143" (this is for IMAP)
and the second
tcpick -i lo -C -yP -T1 -wR "port 689" (this is for the store )