summaryrefslogtreecommitdiff
path: root/gnu/dist/postfix/DEBUG_README
blob: 78d0b6dd5c71236d7e854196a02a3571a0372512 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
1 - Purpose of this document
============================

This document describes how to debug parts of the Postfix mail
system, either by making the software log a lot of detail to the
syslog daemon, or by running some daemon processes under control
of an interactive debugger.

2 - Verbose logging for specific SMTP connections
=================================================

In /etc/postfix/main.cf, list the remote site name or address in
the "debug_peer_list" parameter. For example, in order to make the
software log a lot of information to the syslog daemon for connections
from or to the loopback interface:

    debug_peer_list = 127.0.0.1

You can specify one or more hosts, domains, addresses or net/masks.

3 - Making daemon programs more verbose
=======================================

Append one or more -v options to selected daemon definitions in
/etc/postfix/master.cf and type "postfix reload". This will cause
a lot of activity to be logged to the syslog daemon.

4 - Manually tracing a Postfix daemon process
=============================================

Some systems allow you to inspect a running process with a system
call tracer. For example:

	# trace -p process-id
	# strace -p process-id
	# truss -p process-id
	# ktrace -p process-id

See your system documentation for details.

Tracing a running process can give valuable information about what
a process is attempting to do. This is as much information as you
can get without running an interactive debugger program, as described
in a later section.

5 - Automatically tracing a Postfix daemon process
==================================================

Postfix can attach a call tracer whenever a daemon process starts.

Append a -D option to the suspect command in /etc/postfix/master.cf,
for example:

    smtp      inet  n       -       n       -       -       smtpd -D

Edit the debugger_command definition in /etc/postfix/main.cf so
that it invokes the call tracer of your choice, for example:

    debugger_command =
         PATH=/bin:/usr/bin:/usr/local/bin
         (truss -p $process_id 2>&1 | logger -p mail.info) & sleep 5

Instead of truss use trace or strace.

Type "postfix reload" and watch the logfile.

6 - Running daemon programs under an interactive debugger
=========================================================

Append a -D option to the suspect command in /etc/postfix/master.cf,
for example:

    smtp      inet  n       -       n       -       -       smtpd -D

Edit the debugger_command definition in /etc/postfix/main.cf so
that it invokes the debugger of your choice, for example:

    debugger_command =
         PATH=/usr/bin:/usr/X11R6/bin
         xxgdb $daemon_directory/$process_name $process_id & sleep 5

If you use xxgdb, be sure that gdb is in the command search path.

Export XAUTHORITY so that X access control works, for example:

    % setenv XAUTHORITY ~/.Xauthority

Stop and start the Postfix system. 

Whenever the suspect daemon process is started, a debugger window
pops up and you can watch in detail what happens.

7 - Unreasonable behavior
=========================

Sometimes the behavior exhibit by Postfix just does not match the
source code. Why can a program deviate from the instructions given
by its author? There are two possibilities.

1 - The compiler has messed up.

2 - The hardware has messed up.

In both cases, the program being executed is not the program that
was supposed to be executed, so anything can happen.

Hardware-related failures happen erratically, and they usually do
not reproduce after power cycling and rebooting the system.  There's
little I can do about bad hardware.  Be sure to use hardware that
at the very least can detect memory errors. Otherwise, Postfix will
just be a sitting duck waiting to be hit by a bit error. Critical
systems deserve real hardware.

When a compiler messes up, the problem can be reproduced whenever
the resulting program is run. Compiler errors are most likely to
happen in the code optimizer. If a problem is reproducible across
power cycles and system reboots, it can be worthwhile to rebuild
Postfix with optimization disabled, and to see if optimization
makes a difference.

In order to compile Postfix with optimizations turned off:

    % make tidy
    % make makefiles OPT=

This produces a set of Makefiles that do not request compiler
optomization. 

Once the makefiles are set up, build the software:

    % make
    % su
    # make install

And see if the problem reproduces. If the problem goes away, talk
to your vendor.