Here is an updated version of the patch, as included in the Debian package
of Cyrus IMAPd, release 2.1.4-8. Now the documentation us updated as well.
I've attached one extra file and a patch which I use to help users generate
the debugging information I need to track down bugs. I have also written a
quick guide for building the Debian package with -O0 -g to get symbolic
information for gdb, and about the use of debug_command. If anyone is
curious about it, just download version 2.1.4-8 of the cyrus21-imapd package
from Debian unstable (it should be in all mirrors by tomorrow).
Packagers of Cyrus for distributions are welcome to using the patch and
debugging scripts, but please credit Debian in the documentation. CMU is
welcome to add the debug_command patches to Cyrus under their copyright and
license, and to add the debugging stuff to contrib/ or to their own
documentation, should they wish to do so.
I hope these are useful for someone else out there.
--
"One disk to rule them all, One disk to find them. One disk to bring
them all and in the darkness grind them. In the Land of Redmond
where the shadows lie." -- The Silicon Valley Tarot
Henrique Holschuh
Index: imap/fud.c
===================================================================
RCS file: /home/cvs/debian/cyrus21-imapd/imap/fud.c,v
retrieving revision 1.1.1.4
retrieving revision 1.2
diff -u -r1.1.1.4 -r1.2
--- imap/fud.c 22 Feb 2002 17:25:26 -0000 1.1.1.4
+++ imap/fud.c 14 May 2002 13:18:25 -0000 1.2
@@ -164,9 +164,11 @@
setproctitle_init(argc, argv, envp);
- while ((opt = getopt(argc, argv, "C:")) != EOF) {
+ while ((opt = getopt(argc, argv, "C:D")) != EOF) {
switch (opt) {
case 'C': /* alt config file - handled by service::main() */
+ break;
+ case 'D': /* external debugger - handled by service::main() */
break;
default:
break;
Index: imap/imapd.c
===================================================================
RCS file: /home/cvs/debian/cyrus21-imapd/imap/imapd.c,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- imap/imapd.c 29 Apr 2002 12:17:51 -0000 1.11
+++ imap/imapd.c 14 May 2002 13:18:25 -0000 1.12
@@ -533,9 +533,11 @@
snmp_connect(); /* ignore return code */
snmp_set_str(SERVER_NAME_VERSION,CYRUS_VERSION);
- while ((opt = getopt(argc, argv, "C:sp:")) != EOF) {
+ while ((opt = getopt(argc, argv, "C:Dsp:")) != EOF) {
switch (opt) {
case 'C': /* alt config file - handled by service::main() */
+ break;
+ case 'D': /* external debugger - handled by service::main() */
break;
case 's': /* imaps (do starttls right away) */
imaps = 1;
Index: imap/lmtpd.c
===================================================================
RCS file: /home/cvs/debian/cyrus21-imapd/imap/lmtpd.c,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- imap/lmtpd.c 16 Apr 2002 20:12:42 -0000 1.10
+++ imap/lmtpd.c 14 May 2002 13:18:25 -0000 1.11
@@ -313,9 +313,11 @@
prot_setflushonread(deliver_in, deliver_out);
prot_settimeout(deliver_in, 360);
- while ((opt = getopt(argc, argv, "C:a")) != EOF) {
+ while ((opt = getopt(argc, argv, "C:Da")) != EOF) {
switch(opt) {
case 'C': /* alt config file - handled by service::main() */
+ break;
+ case 'D': /* ext. debugger - handled by service::main() */
break;
case 'a':
Index: imap/lmtpproxyd.c
===================================================================
RCS file: /home/cvs/debian/cyrus21-imapd/imap/lmtpproxyd.c,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- imap/lmtpproxyd.c 30 Apr 2002 19:14:39 -0000 1.9
+++ imap/lmtpproxyd.c 14 May 2002 13:18:25 -0000 1.10
@@ -279,9 +279,11 @@
prot_setflushonread(deliver_in, deliver_out);
prot_settimeout(deliver_in, 300);
- while ((opt = getopt(argc, argv, "C:q")) != EOF) {
+ while ((opt = getopt(argc, argv, "C:Dq")) != EOF) {
switch(opt) {
case 'C': /* alt config file - handled by service::main() */
+ break;
+ case 'D': /* ext debugger - handled by service::main() */
break;
case 'q':
Index: imap/mupdate.c
===================================================================
RCS file: /home/cvs/debian/cyrus21-imapd/imap/mupdate.c,v
retrieving revision 1.1.1.10
retrieving revision 1.2
diff -u -r1.1.1.10 -r1.2
--- imap/mupdate.c 11 Apr 2002 16:05:00 -0000 1.1.1.10
+++ imap/mupdate.c 14 May 2002 13:18:25 -0000 1.2
@@ -352,9 +352,11 @@
}
/* see if we're the master or a slave */
- while ((opt = getopt(argc, argv, "C:m")) != EOF) {
+ while ((opt = getopt(argc, argv, "C:Dm")) != EOF) {
switch (opt) {
case 'C':
+ break;
+ case 'D': /* ext debugger */
break;
case 'm':
masterp = 1;
Index: imap/pop3d.c
===================================================================
RCS file: /home/cvs/debian/cyrus21-imapd/imap/pop3d.c,v
retrieving revision 1.1.1.7
retrieving revision 1.2
diff -u -r1.1.1.7 -r1.2
--- imap/pop3d.c 10 Apr 2002 18:02:42 -0000 1.1.1.7
+++ imap/pop3d.c 14 May 2002 13:18:25 -0000 1.2
@@ -337,9 +337,11 @@
fatal(error_message(r), EC_CONFIG);
}
- while ((opt = getopt(argc, argv, "C:sk")) != EOF) {
+ while ((opt = getopt(argc, argv, "C:Dsk")) != EOF) {
switch(opt) {
case 'C': /* alt config file - handled by service::main() */
+ break;
+ case 'D': /* external debugger - handled by service::main() */
break;
case 's': /* pop3s (do starttls right away) */
Index: imap/pop3proxyd.c
===================================================================
RCS file: /home/cvs/debian/cyrus21-imapd/imap/pop3proxyd.c,v
retrieving revision 1.1.1.8
retrieving revision 1.2
diff -u -r1.1.1.8 -r1.2
--- imap/pop3proxyd.c 23 Apr 2002 18:41:33 -0000 1.1.1.8
+++ imap/pop3proxyd.c 14 May 2002 13:18:25 -0000 1.2
@@ -221,9 +221,11 @@
popd_in = prot_new(0, 0);
popd_out = prot_new(1, 1);
- while ((opt = getopt(argc, argv, "C:sk")) != EOF) {
+ while ((opt = getopt(argc, argv, "C:Dsk")) != EOF) {
switch(opt) {
case 'C': /* alt config file - handled by service::main() */
+ break;
+ case 'D': /* ext. debugger - handled by service::main() */
break;
case 's': /* pop3s (do starttls right away) */
Index: imap/proxyd.c
===================================================================
RCS file: /home/cvs/debian/cyrus21-imapd/imap/proxyd.c,v
retrieving revision 1.1.1.15
retrieving revision 1.2
diff -u -r1.1.1.15 -r1.2
--- imap/proxyd.c 28 Apr 2002 18:12:50 -0000 1.1.1.15
+++ imap/proxyd.c 14 May 2002 13:18:25 -0000 1.2
@@ -927,9 +927,11 @@
mboxlist_init(0);
mboxlist_open(NULL);
- while ((opt = getopt(argc, argv, "C:sp:")) != EOF) {
+ while ((opt = getopt(argc, argv, "C:Dsp:")) != EOF) {
switch (opt) {
case 'C': /* alt config file - handled by service::main() */
+ break;
+ case 'D': /* ext. debugger - handled by service::main() */
break;
case 's': /* imaps (do starttls right away) */
imaps = 1;
Index: man/fud.8
===================================================================
RCS file: /home/cvs/debian/cyrus21-imapd/man/fud.8,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- man/fud.8 21 Apr 2002 15:35:21 -0000 1.2
+++ man/fud.8 14 May 2002 13:18:25 -0000 1.3
@@ -47,6 +47,9 @@
.B \-C
.I config-file
]
+[
+.B \-D
+]
.SH DESCRIPTION
.B FUD
is a long lived datagram daemon started from cyrmaster that provides
@@ -70,6 +73,9 @@
.TP
.BI \-C " config-file"
Read configuration options from \fIconfig-file\fR.
+.TP
+.BI \-D
+Run external debugger specified in debug_command.
.SH FILES
.TP
.B /etc/imapd.conf
Index: man/imapd.8
===================================================================
RCS file: /home/cvs/debian/cyrus21-imapd/man/imapd.8,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- man/imapd.8 25 Nov 2001 18:24:27 -0000 1.2
+++ man/imapd.8 14 May 2002 13:18:25 -0000 1.3
@@ -48,6 +48,9 @@
.I config-file
]
[
+.B \-D
+]
+[
.B \-s
]
[
@@ -106,6 +109,9 @@
.TP
.BI \-C " config-file"
Read configuration options from \fIconfig-file\fR.
+.TP
+.BI \-D
+Run external debugger specified in debug_command.
.TP
.BI \-s
Serve IMAP over SSL (imaps). All data to and from
Index: man/lmtpd.8
===================================================================
RCS file: /home/cvs/debian/cyrus21-imapd/man/lmtpd.8,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- man/lmtpd.8 25 Nov 2001 18:24:27 -0000 1.2
+++ man/lmtpd.8 14 May 2002 13:18:25 -0000 1.3
@@ -48,6 +48,9 @@
.I config-file
]
[
+.B \-D
+]
+[
.B \-a
]
.SH DESCRIPTION
@@ -66,6 +69,9 @@
.TP
.BI \-C " config-file"
Read configuration options from \fIconfig-file\fR.
+.TP
+.BI \-D
+Run external debugger specified in debug_command.
.TP
.BI \-a
Preauthorize connections initiated on an internet socket, instead of
Index: man/notifyd.8
===================================================================
RCS file: /home/cvs/debian/cyrus21-imapd/man/notifyd.8,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- man/notifyd.8 21 Apr 2002 15:35:21 -0000 1.2
+++ man/notifyd.8 14 May 2002 13:18:25 -0000 1.3
@@ -47,6 +47,9 @@
.B \-C
.I config-file
]
+[
+.B \-D
+]
.SH DESCRIPTION
.B Notifyd
is a daemon started from cyrmaster(8) that handles notification requests on
@@ -72,6 +75,9 @@
.TP
.BI \-C " config-file"
Read configuration options from \fIconfig-file\fR.
+.TP
+.BI \-D
+Run external debugger specified in debug_command.
.SH NOTIFICATION METHODS
.TP
.B null
Index: man/pop3d.8
===================================================================
RCS file: /home/cvs/debian/cyrus21-imapd/man/pop3d.8,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- man/pop3d.8 25 Nov 2001 18:24:27 -0000 1.2
+++ man/pop3d.8 14 May 2002 13:18:25 -0000 1.3
@@ -48,6 +48,9 @@
.I config-file
]
[
+.B \-D
+]
+[
.B \-s
]
[
@@ -83,6 +86,9 @@
.TP
.BI \-C " config-file"
Read configuration options from \fIconfig-file\fR.
+.TP
+.BI \-D
+Run external debugger specified in debug_command.
.TP
.BI \-s
Serve POP3 over SSL (pop3s). All data to and from
Index: master/service.c
===================================================================
RCS file: /home/cvs/debian/cyrus21-imapd/master/service.c,v
retrieving revision 1.1.1.5
retrieving revision 1.2
diff -u -r1.1.1.5 -r1.2
--- master/service.c 8 Mar 2002 19:26:17 -0000 1.1.1.5
+++ master/service.c 14 May 2002 13:18:25 -0000 1.2
@@ -138,6 +138,7 @@
#endif
extern void config_init(const char *, const char *);
+extern const char *config_getstring(const char *key, const char *def);
extern const char *config_dir;
static int getlockfd(char *service)
@@ -257,14 +258,18 @@
struct request_info request;
int opt;
char *alt_config = NULL;
+ int call_debugger = 0;
int soctype;
int typelen = sizeof(soctype);
- while ((opt = getopt(argc, argv, "C:")) != EOF) {
+ while ((opt = getopt(argc, argv, "C:D")) != EOF) {
switch (opt) {
case 'C': /* alt config file */
alt_config = optarg;
break;
+ case 'D': /* activate external debugger */
+ call_debugger = 1;
+ break;
default:
break;
}
@@ -291,6 +296,18 @@
}
config_init(alt_config, service);
+ if (call_debugger) {
+ char debugbuf[1024];
+ int ret;
+ const char *debugger = config_getstring("debug_command", (char *) 0);
+ if (debugger) {
+ snprintf(debugbuf, sizeof(debugbuf), debugger,
+ argv[0], getpid(), service);
+ syslog(LOG_DEBUG, "running external debugger: %s", debugbuf);
+ ret = system(debugbuf); /* run debugger */
+ syslog(LOG_DEBUG, "debugger returned exit status: %d", ret);
+ }
+ }
syslog(LOG_DEBUG, "executed");
/* set close on exec */
Index: notifyd/notifyd.c
===================================================================
RCS file: /home/cvs/debian/cyrus21-imapd/notifyd/notifyd.c,v
retrieving revision 1.1.1.6
retrieving revision 1.2
diff -u -r1.1.1.6 -r1.2
--- notifyd/notifyd.c 8 Apr 2002 20:49:26 -0000 1.1.1.6
+++ notifyd/notifyd.c 14 May 2002 13:18:25 -0000 1.2
@@ -215,9 +215,11 @@
config_changeident("notifyd");
if (geteuid() == 0) fatal("must run as the Cyrus user", EC_USAGE);
- while ((opt = getopt(argc, argv, "C:m:")) != EOF) {
+ while ((opt = getopt(argc, argv, "C:Dm:")) != EOF) {
switch(opt) {
case 'C': /* alt config file - handled by service::main() */
+ break;
+ case 'D': /* ext debugger - handled by service::main() */
break;
case 'm':
Index: debian/imapd.conf
===================================================================
RCS file: /home/cvs/debian/cyrus21-imapd/debian/imapd.conf,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- debian/imapd.conf 11 May 2002 18:53:47 -0000 1.7
+++ debian/imapd.conf 14 May 2002 13:18:25 -0000 1.8
@@ -202,3 +202,17 @@
# Unix domain socket that the new mail notification daemon listens on.
notifysocket: /var/run/cyrus/socket/notify
+##
+## DEBUGGING
+##
+# Debugging hook. See /usr/share/doc/cyrus21-common/README.Debian.debug
+# Keep the hook disabled when it is not in use
+#
+# gdb Back-traces
+#debug_command: /usr/bin/gdb -batch -cd=/tmp -x /usr/lib/cyrus/get-backtrace.gdb
+/usr/lib/cyrus/bin/%s %d >/tmp/gdb-backtrace.cyrus.%1$s.%2$d <&- 2>&1 &
+#
+# system-call traces
+#debug_command: /usr/bin/strace -tt -o /tmp/strace.cyrus.%s.%d -p %2$d <&- 2>&1 &
+#
+# library traces
+#debug_command: /usr/bin/ltrace -tt -n 2 -o /tmp/ltrace.cyrus.%s.%d -p %2$d <&- 2>&1 &
c
bt
quit
