1 files changed, 183 insertions, 0 deletions
diff --git a/proto/MAILLOG_README.html b/proto/MAILLOG_README.html
new file mode 100644
index 0000000..5a19a92
--- /dev/null
+++ b/proto/MAILLOG_README.html
@@ -0,0 +1,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=utf-8">
+
+</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 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>
+
+<blockquote>
+<pre>
+# postfix stop
+# postconf maillog_file=/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 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>
+
+</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) and postqueue(1).
+
+</ul>
+
+</body>
+
+</html>