summaryrefslogtreecommitdiffstats
path: root/proto/MAILLOG_README.html
blob: 13c1091e8fd39ce9197730b3faa817bf649b8ecf (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
184
185
186
187
188
189
190
191
192
193
194
195
<!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=utf-8">
<link rel='stylesheet' type='text/css' href='postfix-doc.css'>

</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 its 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 master.cf 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>

<p> In the example below, specifying maillog_file_permissions is
optional (Postfix 3.9 and later). The default value is 0600, i.e.,
only the super-user can access the file; the value 0644 also
adds 'group' and 'other' read access. </p>

<blockquote>
<pre>
# postfix stop
# postconf maillog_file=/var/log/postfix.log
# postconf maillog_file_permissions=0644 # (Postfix 3.9 and later)
# 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 maillog_file_prefixes
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 master.cf 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 main.cf with "maillog_file = /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
maillog_file_rotate_suffix parameter (default: %Y%m%d-%H%M%S). </p>

<li> <p> Reload Postfix so that postlogd(8) immediately closes the
old logfile. </p>

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

<li> <p> The next time it logs an event, postlogd(8) will create a
new logfile, with permissions specified with the maillog_file_permissions
parameter (default: 0600). </p>

</ul>

<p> Notes: </p>

<ul>

<li> <p> This command will not rotate a logfile with a 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 the Postfix logfile or stdout requires the Postfix
postlogd(8) 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 main.cf parameters.

<li> <p> If Postfix is down, the non-daemon programs postfix(1),
postsuper(1), postmulti(1), and postlog(1), will log directly to
$maillog_file. 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 $maillog_file (also, logging to stdout would interfere with the
operation of some of these programs). These programs can log to
postlogd(8) 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 postdrop(1), postqueue(1), and (Postfix &ge; 3.7)
postlog(1).

</ul>

</body>

</html>