1<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" 2 "http://www.w3.org/TR/html4/loose.dtd"> 3 4<html> 5 6<head> 7 8<title>Postfix logging to file or stdout</title> 9 10<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 11<link rel='stylesheet' type='text/css' href='postfix-doc.css'> 12 13</head> 14 15<body> 16 17<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix 18logging to file or stdout</h1> 19 20<hr> 21 22<h2>Overview </h2> 23 24<p> Postfix supports its own logging system as an alternative to 25syslog (which remains the default). This is available with Postfix 26version 3.4 or later. </p> 27 28<p> Topics covered in this document: </p> 29 30<ul> 31 32<li><a href="#log-to-file">Configuring logging to file</a> 33 34<li><a href="#log-to-stdout">Configuring logging to stdout</a> 35 36<li><a href="#logrotate">Rotating logs </a> 37 38<li><a href="#limitations">Limitations</a> 39 40</ul> 41 42<h2> <a name="log-to-file"> Configuring logging to file </a> </h2> 43 44<p> Logging to file solves a usability problem for MacOS, and 45eliminates multiple problems for systemd-based systems. </p> 46 47<ol> 48 49<li> <p> Add the following line to master.cf if not already present 50(note: there must be no whitespace at the start of the line): </p> 51 52<blockquote> 53<pre> 54postlog unix-dgram n - n - 1 postlogd 55</pre> 56</blockquote> 57 58<p> Note: the service type "<b>unix-dgram</b>" was introduced with 59Postfix 3.4. Remove the above line before backing out to an older 60Postfix version. </p> 61 62<li> <p> Configure Postfix to write logging, to, for example, 63/var/log/postfix.log. See also the "<a href="#logrotate">Logfile 64rotation</a>" section below for logfile management. </p> 65 66<blockquote> 67<pre> 68# postfix stop 69# postconf maillog_file=/var/log/postfix.log 70# postfix start 71</pre> 72</blockquote> 73 74<p> By default, the logfile name must start with "/var" or "/dev/stdout" 75(the list of allowed prefixes is configured with the maillog_file_prefixes 76parameter). This safety mechanism limits the damage from a single 77configuration mistake. </p> 78 79</ol> 80 81<h2> <a name="log-to-stdout"> Configuring logging to stdout </a> </h2> 82 83<p> Logging to stdout is useful when Postfix runs in a container, 84as it eliminates a syslogd dependency. </p> 85 86<ol> 87 88<li> <p> Add the following line to master.cf if not already present (note: 89there must be no whitespace at the start of the line): </p> 90 91<blockquote> 92<pre> 93postlog unix-dgram n - n - 1 postlogd 94</pre> 95</blockquote> 96 97<p> Note: the service type "<b>unix-dgram</b>" was introduced with 98Postfix 3.4. Remove the above line before backing out to an older 99Postfix version. </p> 100 101<li> <p> Configure main.cf with "maillog_file = /dev/stdout". </p> 102 103<li> <p> Start Postfix with "<b>postfix start-fg</b>". </p> 104 105</ol> 106 107<h2> <a name="logrotate"> Rotating logs </a> </h2> 108 109<p> The command "<b>postfix logrotate</b>" may be run by hand or 110by a cronjob. It logs all errors, and reports errors to stderr if 111run from a terminal. This command implements the following steps: 112</p> 113 114<ul> 115 116<li> <p> Rename the current logfile by appending a suffix that 117contains the date and time. This suffix is configured with the 118maillog_file_rotate_suffix parameter (default: %Y%m%d-%H%M%S). </p> 119 120<li> <p> Reload Postfix so that postlogd(8) immediately closes the 121old logfile. </p> 122 123<li> <p> After a brief pause, compress the old logfile. The compression 124program is configured with the maillog_file_compressor parameter 125(default: gzip). </p> 126 127</ul> 128 129<p> Notes: </p> 130 131<ul> 132 133<li> <p> This command will not rotate a logfile with a pathname under 134the /dev directory, such as /dev/stdout. </p> 135 136<li> <p> This command does not (yet) remove old logfiles. </p> 137 138</ul> 139 140<h2> <a name="limitations">Limitations</a> </h2> 141 142<p> Background: </p> 143 144<ul> 145 146<li> <p> Postfix consists of a number of daemon programs that run 147in the background, as well as non-daemon programs for local mail 148submission or Postfix management. 149 150<li> <p> Logging to the Postfix logfile or stdout requires the Postfix 151postlogd(8) service. This ensures that simultaneous logging from 152different programs will not get mixed up. </p> 153 154<li> <p> All Postfix programs can log to syslog, but not all programs 155have sufficient privileges to use the Postfix logging service, and 156many non-daemon programs must not log to stdout as that would corrupt 157their output. </p> 158 159</ul> 160 161<p> Limitations: </p> 162 163<ul> 164 165<li> <p> Non-daemon Postfix programs will log errors to syslogd(8) 166before they have processed command-line options and main.cf parameters. 167 168<li> <p> If Postfix is down, the non-daemon programs postfix(1), 169postsuper(1), postmulti(1), and postlog(1), will log directly to 170$maillog_file. These programs expect to run with root privileges, 171for example during Postfix start-up, reload, or shutdown. 172 173<li> <p> Other non-daemon Postfix programs will never write directly 174to $maillog_file (also, logging to stdout would interfere with the 175operation of some of these programs). These programs can log to 176postlogd(8) if they are run by the super-user, or if their executable 177file has set-gid permission. Do not set this permission on programs 178other than postdrop(1), postqueue(1), and (Postfix ≥ 3.7) 179postlog(1). 180 181</ul> 182 183</body> 184 185</html> 186
