summaryrefslogtreecommitdiffstats
path: root/html/MAILLOG_README.html
blob: aa371ba26cd672cacba12a9053f4a83ad63ac805 (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
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/html4/loose.dtd">

<html>

<head>

<title>Postfix logging to file or stdout</title>

<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">

</head>

<body>

<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix
logging to file or stdout</h1>

<hr>

<h2>Overview </h2>

<p> Postfix supports it own logging system as an alternative to
syslog (which remains the default). This is available with Postfix
version 3.4 or later. </p>

<p> Topics covered in this document: </p>

<ul>

<li><a href="#log-to-file">Configuring logging to file</a>

<li><a href="#log-to-stdout">Configuring logging to stdout</a>

<li><a href="#logrotate">Rotating logs </a>

<li><a href="#limitations">Limitations</a>

</ul>

<h2> <a name="log-to-file"> Configuring logging to file </a> </h2>

<p> Logging to file solves a usability problem for MacOS, and
eliminates multiple problems for systemd-based systems. </p>

<ol>

<li> <p> Add the following line to <a href="master.5.html">master.cf</a> if not already present
(note: there must be no whitespace at the start of the line): </p>

<blockquote>
<pre>
postlog   unix-dgram n  -       n       -       1       postlogd
</pre>
</blockquote>

<p> Note: the service type "<b>unix-dgram</b>" was introduced with 
Postfix 3.4. Remove the above line before backing out to an older
Postfix version. </p>

<li> <p> Configure Postfix to write logging, to, for example,
/var/log/postfix.log. See also the "<a href="#logrotate">Logfile
rotation</a>" section below for logfile management. </p>

<blockquote>
<pre>
# postfix stop
# postconf <a href="postconf.5.html#maillog_file">maillog_file</a>=/var/log/postfix.log
# postfix start
</pre>
</blockquote>

<p> By default, the logfile name must start with "/var" or "/dev/stdout"
(the list of allowed prefixes is configured with the <a href="postconf.5.html#maillog_file_prefixes">maillog_file_prefixes</a>
parameter). This safety mechanism limits the damage from a single
configuration mistake. </p>

</ol>

<h2> <a name="log-to-stdout"> Configuring logging to stdout </a> </h2>

<p> Logging to stdout is useful when Postfix runs in a container,
as it eliminates a syslogd dependency. </p>

<ol>

<li> <p> Add the following line to <a href="master.5.html">master.cf</a> if not already present (note:
there must be no whitespace at the start of the line): </p>

<blockquote>
<pre>
postlog   unix-dgram n  -       n       -       1       postlogd
</pre>
</blockquote>

<p> Note: the service type "<b>unix-dgram</b>" was introduced with 
Postfix 3.4. Remove the above line before backing out to an older
Postfix version. </p>

<li> <p> Configure <a href="postconf.5.html">main.cf</a> with "<a href="postconf.5.html#maillog_file">maillog_file</a> = /dev/stdout". </p> 

<li> <p> Start Postfix with "<b>postfix start-fg</b>". </p>

</ol>

<h2> <a name="logrotate"> Rotating logs </a> </h2>

<p> The command "<b>postfix logrotate</b>" may be run by hand or
by a cronjob. It logs all errors, and reports errors to stderr if
run from a terminal. This command implements the following steps:
</p>

<ul>

<li> <p> Rename the current logfile by appending a suffix that
contains the date and time. This suffix is configured with the
<a href="postconf.5.html#maillog_file_rotate_suffix">maillog_file_rotate_suffix</a> parameter (default: %Y%m%d-%H%M%S). </p>

<li> <p> Reload Postfix so that <a href="postlogd.8.html">postlogd(8)</a> immediately closes the
old logfile. </p>

<li> <p> After a brief pause, compress the old logfile. The compression
program is configured with the <a href="postconf.5.html#maillog_file_compressor">maillog_file_compressor</a> parameter
(default: gzip). </p>

</ul>

<p> Notes: </p>

<ul>

<li> <p> This command will not rotate a logfile with pathname under
the /dev directory, such as /dev/stdout. </p>

<li> <p> This command does not (yet) remove old logfiles. </p>

</ul>

<h2> <a name="limitations">Limitations</a> </h2>

<p> Background: </p>

<ul>

<li> <p> Postfix consists of a number of daemon programs that run
in the background, as well as non-daemon programs for local mail
submission or Postfix management.

<li> <p> Logging to Postfix logfile or stdout requires the Postfix
<a href="postlogd.8.html">postlogd(8)</a> service. This ensures that simultaneous logging from
different programs will not get mixed up. </p>

<li> <p> All Postfix programs can log to syslog, but not all programs
have sufficient privileges to use the Postfix logging service, and
many non-daemon programs must not log to stdout as that would corrupt
their output. </p>

</ul>

<p> Limitations: </p>

<ul>

<li> <p> Non-daemon Postfix programs will log errors to syslogd(8)
before they have processed command-line options and <a href="postconf.5.html">main.cf</a> parameters.

<li> <p> If Postfix is down, the non-daemon programs <a href="postfix.1.html">postfix(1)</a>,
<a href="postsuper.1.html">postsuper(1)</a>, <a href="postmulti.1.html">postmulti(1)</a>, and <a href="postlog.1.html">postlog(1)</a>, will log directly to
$<a href="postconf.5.html#maillog_file">maillog_file</a>. These programs expect to run with root privileges,
for example during Postfix start-up, reload, or shutdown.

<li> <p> Other non-daemon Postfix programs will never write directly
to $<a href="postconf.5.html#maillog_file">maillog_file</a> (also, logging to stdout would interfere with the
operation of some of these programs). These programs can log to
<a href="postlogd.8.html">postlogd(8)</a> if they are run by the super-user, or if their executable
file has set-gid permission. Do not set this permission on programs
other than <a href="postdrop.1.html">postdrop(1)</a> and <a href="postqueue.1.html">postqueue(1)</a>.

</ul>

</body>

</html>