Hi Philipp, thanks for the
interest.
Let's begin from the nice parts:
> Finally, I don't care about which section they
are in, I always just
> type man XXX.
Great! So it's decided that all the shared control files will be put in Section 9 with their proper names: ldaprebind(9), ldapbasedn(9), etc.
> type man XXX.
Great! So it's decided that all the shared control files will be put in Section 9 with their proper names: ldaprebind(9), ldapbasedn(9), etc.
Now, we won't go to the bad parts, but to the
polemic parts, ok? :-)
>> Do we agree on this issue? (i hope
so)
>
> No. If I want to know something about a specific control file, usually
> that means, that I don't know anything or much about it - so I also
> don't know which program it uses. It makes the thing just harder to
> document these control files inside the manpage for the program that
> uses it.
So you're telling me you don't like stock Qmail documentation, where all of its 29 control files were already documented in this manner.
>
> No. If I want to know something about a specific control file, usually
> that means, that I don't know anything or much about it - so I also
> don't know which program it uses. It makes the thing just harder to
> document these control files inside the manpage for the program that
> uses it.
So you're telling me you don't like stock Qmail documentation, where all of its 29 control files were already documented in this manner.
You are telling me that you don't want anymore this
routine you always had in Qmail, that is, reading the qmail-control(5)
manpage to know, say, the "virtualdomains" control file is documented
inside qmail-send(8).
This routine always existed. Before I met
qmail-ldap (and even after that) I always had to check on qmail-control(5) to
know where a certain control file is documented.
This procedure was not invented by me. And I
don't believe there is a need to change it, since people are already used to
it.
If we want to change this routine, we not only need
to create the manpages for the control files added by qmail-ldap, but we also
would need to remove these 29 control files from their manpages, so that people
can do a "man smtproutes" as they would with "man ldaprebind".
Bellow is
the stock Qmail qmail-smtpd manpage. Can you imagine it without
it's control files?
NAME
qmail-smtpd - receive mail via SMTP
SYNOPSIS
qmail-smtpd
DESCRIPTION
qmail-smtpd receives mail messages via the Simple Mail
Transfer Protocol (SMTP) and invokes qmail-queue to deposit
them into the outgoing queue. qmail-smtpd must be supplied
several environment variables; see tcp-environ(5).
qmail-smtpd is responsible for counting hops. It rejects
any message with 100 or more Received or Delivered-To header
fields.
qmail-smtpd supports ESMTP, including the 8BITMIME and
PIPELINING options.
TRANSPARENCY
qmail-smtpd converts the SMTP newline convention into the
UNIX newline convention by converting CR LF into LF. It
returns a temporary error and drops the connection on bare
LFs; see http://pobox.com/~djb/docs/smtplf.html.
qmail-smtpd accepts messages that contain long lines or
non-ASCII characters, even though such messages violate the
SMTP protocol.
CONTROL FILES
badmailfrom
Unacceptable envelope sender addresses. qmail-smtpd
will reject every recipient address for a message if
the envelope sender address is listed in badmailfrom.
A line in badmailfrom may be of the form @host, meaning
every address at host.
databytes
Maximum number of bytes allowed in a message, or 0 for
no limit. Default: 0. If a message exceeds this
limit, qmail-smtpd returns a permanent error code to
the client; in contrast, if the disk is full or qmail-
smtpd hits a resource limit, qmail-smtpd returns a
temporary error code.
databytes counts bytes as stored on disk, not as
transmitted through the network. It does not count the
qmail-smtpd Received line, the qmail-queue Received
line, or the envelope.
If the environment variable DATABYTES is set, it
overrides databytes.
localiphost
Replacement host name for local IP addresses. Default:
me, if that is supplied. qmail-smtpd is responsible
for recognizing dotted-decimal addresses for the
current host. When it sees a recipient address of the
form [EMAIL PROTECTED], where d.d.d.d is a local IP
address, it replaces [d.d.d.d] with localiphost. This
is done before rcpthosts.
morercpthosts
Extra allowed RCPT domains. If rcpthosts and
morercpthosts both exist, morercpthosts is effectively
appended to rcpthosts.
You must run qmail-newmrh whenever morercpthosts
changes.
Rule of thumb for large sites: Put your 50 most
commonly used domains into rcpthosts, and the rest into
morercpthosts.
rcpthosts
Allowed RCPT domains. If rcpthosts is supplied,
qmail-smtpd will reject any envelope recipient address
with a domain not listed in rcpthosts.
Exception: If the environment variable RELAYCLIENT is
set, qmail-smtpd will ignore rcpthosts, and will append
the value of RELAYCLIENT to each incoming recipient
address.
rcpthosts may include wildcards:
heaven.af.mil
.heaven.af.mil
Envelope recipient addresses without @ signs are always
allowed through.
smtpgreeting
SMTP greeting message. Default: me, if that is
supplied; otherwise qmail-smtpd will refuse to run.
The first word of smtpgreeting should be the current
host's name.
timeoutsmtpd
Number of seconds qmail-smtpd will wait for each new
buffer of data from the remote SMTP client. Default:
1200.
qmail-smtpd - receive mail via SMTP
SYNOPSIS
qmail-smtpd
DESCRIPTION
qmail-smtpd receives mail messages via the Simple Mail
Transfer Protocol (SMTP) and invokes qmail-queue to deposit
them into the outgoing queue. qmail-smtpd must be supplied
several environment variables; see tcp-environ(5).
qmail-smtpd is responsible for counting hops. It rejects
any message with 100 or more Received or Delivered-To header
fields.
qmail-smtpd supports ESMTP, including the 8BITMIME and
PIPELINING options.
TRANSPARENCY
qmail-smtpd converts the SMTP newline convention into the
UNIX newline convention by converting CR LF into LF. It
returns a temporary error and drops the connection on bare
LFs; see http://pobox.com/~djb/docs/smtplf.html.
qmail-smtpd accepts messages that contain long lines or
non-ASCII characters, even though such messages violate the
SMTP protocol.
CONTROL FILES
badmailfrom
Unacceptable envelope sender addresses. qmail-smtpd
will reject every recipient address for a message if
the envelope sender address is listed in badmailfrom.
A line in badmailfrom may be of the form @host, meaning
every address at host.
databytes
Maximum number of bytes allowed in a message, or 0 for
no limit. Default: 0. If a message exceeds this
limit, qmail-smtpd returns a permanent error code to
the client; in contrast, if the disk is full or qmail-
smtpd hits a resource limit, qmail-smtpd returns a
temporary error code.
databytes counts bytes as stored on disk, not as
transmitted through the network. It does not count the
qmail-smtpd Received line, the qmail-queue Received
line, or the envelope.
If the environment variable DATABYTES is set, it
overrides databytes.
localiphost
Replacement host name for local IP addresses. Default:
me, if that is supplied. qmail-smtpd is responsible
for recognizing dotted-decimal addresses for the
current host. When it sees a recipient address of the
form [EMAIL PROTECTED], where d.d.d.d is a local IP
address, it replaces [d.d.d.d] with localiphost. This
is done before rcpthosts.
morercpthosts
Extra allowed RCPT domains. If rcpthosts and
morercpthosts both exist, morercpthosts is effectively
appended to rcpthosts.
You must run qmail-newmrh whenever morercpthosts
changes.
Rule of thumb for large sites: Put your 50 most
commonly used domains into rcpthosts, and the rest into
morercpthosts.
rcpthosts
Allowed RCPT domains. If rcpthosts is supplied,
qmail-smtpd will reject any envelope recipient address
with a domain not listed in rcpthosts.
Exception: If the environment variable RELAYCLIENT is
set, qmail-smtpd will ignore rcpthosts, and will append
the value of RELAYCLIENT to each incoming recipient
address.
rcpthosts may include wildcards:
heaven.af.mil
.heaven.af.mil
Envelope recipient addresses without @ signs are always
allowed through.
smtpgreeting
SMTP greeting message. Default: me, if that is
supplied; otherwise qmail-smtpd will refuse to run.
The first word of smtpgreeting should be the current
host's name.
timeoutsmtpd
Number of seconds qmail-smtpd will wait for each new
buffer of data from the remote SMTP client. Default:
1200.
I think that, instead of removing these control
files from qmail-smtp(8) we should let them there where they are, add the new
control files introduced by qmail-ldap to qmail-smtpd(8).
This is easier for the reader that issuing the
sequence of commands (simulating that all the control files were put in
individual manpages):
man qmail-smtpd
(then the reader discovers qmail-smtpd
has 15 control files, but they're not documented inside
qmail-smtpd(8))
man timeoutsmtpd
man rbllist
man localiphost
man databytes
man smtpgreeting
man smtpcert
man badmailfrom
man badmailfrom-unknown
man relaymailfrom
man etc... man 15
times
To me this is more difficult and not natural since
everybody was already used to have the control files documented inside the
program's manpage.
What do you think of all this?
Regards,
bruno.
