1.1 --- a/man/masqmail.8	Tue Dec 07 14:07:25 2010 -0300
     1.2 +++ b/man/masqmail.8	Tue Dec 07 14:19:04 2010 -0300
     1.3 @@ -27,18 +27,69 @@
     1.4  It replaces sendmail or other MTAs such as qmail or exim.
     1.5  
     1.6  
     1.7 +.SH OPERATION MODES
     1.8 +
     1.9 +Masqmail operates in one of several exclusive modes.
    1.10 +
    1.11 +The daemon mode has two flavors that may be,
    1.12 +and usually are, combined:
    1.13 +.TP
    1.14 +.B \-bd
    1.15 +listen daemon; listens for incoming SMTP connections.
    1.16 +.TP
    1.17 +.B \-q\fRINTERVAL
    1.18 +queue daemon; processes the queue in a regular interval.
    1.19 +
    1.20 +.P
    1.21 +The queue processing mode has two flavors that may be combined:
    1.22 +.TP
    1.23 +.BR \-q
    1.24 +(without argument)
    1.25 +do a single queue run.
    1.26 +.TP
    1.27 +.B \-qo
    1.28 +do a single queue run and deliver only using a specific online route.
    1.29 +
    1.30 +.P
    1.31 +The other modes are simple ones:
    1.32 +.TP
    1.33 +.B \-bi
    1.34 +a no-op for masqmail, just exit.
    1.35 +.TP
    1.36 +.B \-bm
    1.37 +accept messages on stdin. (The default)
    1.38 +.TP
    1.39 +.B \-bp
    1.40 +print the contents of the queue.
    1.41 +.TP
    1.42 +.B \-bs
    1.43 +accept messages by speaking SMTP on stdin.
    1.44 +.TP
    1.45 +.B \-bV
    1.46 +print version information.
    1.47 +.TP
    1.48 +.B \-Mrm
    1.49 +remove messages from the queue.
    1.50 +.P
    1.51 +Some of the modes are also available by calling masqmail
    1.52 +under a special name.
    1.53 +
    1.54 +When no mode had been specified by either one of the above command line
    1.55 +options or by calling masqmail under a special name,
    1.56 +then the default mode \fB\-bm\fR
    1.57 +(i.e. accept messages on stdin) is entered.
    1.58 +However, if neither address arguments are specified nor
    1.59 +\fB\-t\fR is given, then no recipients are available and thus mail can not
    1.60 +be sent, hence something more useful is done: \fB\-bV\fP is assumed.
    1.61 +
    1.62 +
    1.63  .SH OPTIONS
    1.64  
    1.65 -Since masqmail is intended to replace sendmail, it uses the same command line options,
    1.66 +Since masqmail is intended to replace sendmail,
    1.67 +it uses the same command line options,
    1.68  but not all are implemented.
    1.69  The \fB\-qo\fP option is additional, and unique to masqmail.
    1.70  
    1.71 -When no mode had been specified by either a command line option
    1.72 -(e.g. \fB\-bd\fP, \fB\-bs\fP) or by calling masqmail under a special name
    1.73 -(e.g. ``mailq''), then the default mode is used.
    1.74 -This is accepting messages on stdin if any address arguments are given,
    1.75 -and only printing its version (\fB\-bV\fP) otherwise.
    1.76 -
    1.77  .TP
    1.78  \fB\-\-\fR
    1.79  
    1.80 @@ -49,7 +100,8 @@
    1.81  .TP
    1.82  \fB\-bd\fR
    1.83  
    1.84 -Run as daemon, accepting connections, usually on port 25 if not configured differently.
    1.85 +Run as daemon, accepting connections,
    1.86 +usually on port 25 if not configured differently.
    1.87  This is usually used in the startup script at system boot and together with
    1.88  the \fB\-q\fR option (see below).
    1.89  
    1.90 @@ -57,13 +109,21 @@
    1.91  \fB\-bi\fR
    1.92  
    1.93  Old sendmail rebuilds its alias database when invoked with this option.
    1.94 -Masqmail ignores it.
    1.95  Masqmail reads directly from the file given with `alias_file' in the config file.
    1.96 +Hence masqmail simply exits in this mode.
    1.97 +
    1.98 +.TP
    1.99 +.B \-bm
   1.100 +
   1.101 +Accept a text message on stdin.
   1.102 +This is the default mode of operation.
   1.103 +One will hardly use this switch as it is the default.
   1.104  
   1.105  .TP
   1.106  \fB\-bp\fR
   1.107  
   1.108 -Show the messages in the queue. Same as calling masqmail as `mailq'.
   1.109 +Show the messages in the queue.
   1.110 +Same as calling masqmail as `mailq'.
   1.111  
   1.112  .TP
   1.113  \fB\-bs\fR
   1.114 @@ -73,6 +133,11 @@
   1.115  It can also be used to call masqmail from inetd.
   1.116  
   1.117  .TP
   1.118 +\fB\-bV \fR
   1.119 +
   1.120 +Show version information, then exit.
   1.121 +
   1.122 +.TP
   1.123  \fB\-B \fIarg\fR
   1.124  
   1.125  \fIarg\fR is usually 8BITMIME.
   1.126 @@ -86,11 +151,6 @@
   1.127  This is the same practice as that of exim (but different to sendmail).
   1.128  
   1.129  .TP
   1.130 -\fB\-bV \fR
   1.131 -
   1.132 -Show version information.
   1.133 -
   1.134 -.TP
   1.135  \fB\-C \fIfilename\fR
   1.136  
   1.137  Use another configuration than \fI/etc/masqmail/masqmail.conf\fR.
   1.138 @@ -125,9 +185,10 @@
   1.139  .TP
   1.140  \fB\-Mrm \fImsgid...\fR
   1.141  
   1.142 +``Queue manipulation mode''
   1.143 +
   1.144  Remove given messages from the queue.
   1.145 -Privileged users may remove any message,
   1.146 -other users only their own.
   1.147 +Privileged users may remove any message, other users only their own.
   1.148  The message identifiers are listed in the output of
   1.149  \fImasqmail \-bp\fP (aka. \fImailq\fR).
   1.150  
   1.151 @@ -153,8 +214,10 @@
   1.152  
   1.153  ``Do Queueing''
   1.154  Do not attempt to deliver immediately.
   1.155 -Any messages will be queued until the next queue running process picks them up and delivers them.
   1.156 -You get the same effect by setting the do_queue option in /etc/masqmail/masqmail.conf.
   1.157 +Any messages will be queued until the next queue running process picks them
   1.158 +up and delivers them.
   1.159 +You get the same effect by setting the do_queue option in
   1.160 +/etc/masqmail/masqmail.conf.
   1.161  
   1.162  .TP
   1.163  \fB\-oi\fR
   1.164 @@ -172,33 +235,50 @@
   1.165  .TP
   1.166  \fB\-q [\fIinterval\fB]\fR
   1.167  
   1.168 -If not given with an argument, run a queue process, i.e. try to deliver all messages in the queue.
   1.169 -Masqmail sends only to those addresses that are on the local net, not to those that are outside.
   1.170 -Use \fB\-qo\fR for those.
   1.171 +Without argument:
   1.172 +Do a single queue run, i.e. try to deliver all messages in the queue.
   1.173 +Masqmail sends to addresses on the local host, on the local net,
   1.174 +and if it detects an online connection, to remote ones too.
   1.175 +That means, that masqmail sends any queued mail it can.
   1.176 +.B \-q
   1.177 +includes
   1.178 +.B \-qo
   1.179 +(without argument).
   1.180  
   1.181 -If you have configured inetd to start masqmail,
   1.182 -you can use this option in a cron job which starts in regular time intervals,
   1.183 -to mimic the same effect as starting masqmail with \fB\-bd \-q30m\fR.
   1.184 +With an argument:
   1.185 +Start as a daemon and do a queue run automatically once in the specified
   1.186 +time interval.
   1.187 +This is usually used together with \fB\-bd\fR (see above).
   1.188  
   1.189 -An argument may be a time interval i.e. a numerical value followed by one of the letters.
   1.190 -s,m,h,d,w which are interpreted as seconds, minutes, hours, days or weeks respectively.
   1.191 +An argument may be a time interval i.e. a numerical value followed by one
   1.192 +of the letters s,m,h,d,w which are interpreted as
   1.193 +seconds, minutes, hours, days or weeks respectively.
   1.194  Example: \fB\-q30m\fR.
   1.195 -Masqmail starts as a daemon and a queue runner process will be started automatically
   1.196 -once in this time interval.
   1.197 -This is usually used together with \fB\-bd\fR (see above).
   1.198 +
   1.199 +Running masqmail from inetd and starting single queue runs from cron
   1.200 +mimics the same effect as starting masqmail with something like
   1.201 +\fB\-bd \-q30m\fR.
   1.202  
   1.203  .TP
   1.204  \fB\-qo [\fIname\fB]\fR
   1.205  
   1.206 -Can be followed by a connection name.
   1.207 +Online queue runs.
   1.208 +
   1.209 +Without a connection name:
   1.210 +Determine the online status with the configured method
   1.211 +(see \fBonline_detect\fR in \fBmasqmail.conf(5)\fR)
   1.212 +and, if a connection is available, send remote mail over it.
   1.213 +
   1.214 +With a connection name:
   1.215 +Send remote mail over the specified connection,
   1.216 +no online detection is made.
   1.217 +
   1.218 +The specified route configuration is read and queued mail to remote
   1.219 +recipients will be sent.
   1.220 +The \fIname\fR is defined in the configuration (see \fBonline_routes.\fIname\fR).
   1.221 +
   1.222  Use this option in your script which starts as soon as a link to the internet
   1.223  has been set up (usually ip-up).
   1.224 -When masqmail is called with this option, the specified route configuration
   1.225 -is read and the queued mail with destinations on the internet will be sent.
   1.226 -The \fIname\fR is defined in the configuration (see \fBonline_routes.\fIname\fR).
   1.227 -
   1.228 -If called without \fIname\fR the online status is determined with the configured
   1.229 -method (see \fBonline_detect\fR in \fBmasqmail.conf(5)\fR)
   1.230  
   1.231  .TP
   1.232  \fB\-t\fR