Bug#305443: Re: Bug#305443: smtp-auth documentation is incomplete

[Drew Parsons]

On Sun, 2005-05-01 at 12:47 +0200, Marc Haber wrote:

> Can you check the current version of the file,
> http://svn.debian.org/wsvn/pkg-exim4/exim/trunk/debian/README.SMTP-AUTH?op=file&rev=0&sc=0,
> and say whether the docs are ok now. If not, please say what should be
> changed.
> 

Thanks for looking over it further.

As far as I can tell, the file in svn for README.SMTP-AUTH is the same
as already in sid. The text I'm referring to reads:

-----
If you need to enable them for unencrypted connections because your
service provider does support neither TLS encryption nor the CRAM MD5
authentication method, you can do so by setting the appropriate macro
as mentioned in the comments in the configuration file [3].
...
[3] If you are using split configuration (dc_use_split_config='true'
in /etc/exim4/update-exim4.conf.conf), the file to edit is
/etc/exim4/conf.d/auth/30_exim4-config_examples. If you are not using
split configuration, your file is /etc/exim4/exim4.conf.template.
-----

The problematic phrase is "setting the appropriate macro as mentioned
in the comments in the configuration file". That is to say, this phrase
is clear on its own, it tells me that I will find further instructions
in /etc/exim4/conf.d/auth/30_exim4-config_examples.  

The problem is when I look for these instructions inside
30_exim4-config_examples.  I can't find them.  I can't see where your
latest svn version of 30_exim4-config_examples is located, the one at
http://svn.debian.org/wsvn/pkg-exim4/exim4-config-medium/trunk/exim4-config-medium/debian/config/conf.d/conf.d/auth/30_exim4-config-medium_examples?op=file&rev=0&sc=0,

When I read /etc/exim4/conf.d/auth/30_exim4-config_examples (4.50-6), I see these instructions:
#################################
##############
# See /usr/share/doc/exim4-base/README.SMTP-AUTH
##############

# These examples below are the equivalent for client side authentication.
# They get the passwords from CONFDIR/passwd.client. This file should have
# three columns separated by colons, the first contains the name of the
# mailserver to authenticate against, the second the username and the third
# contains the password.

### # example for CONFDIR/passwd.client
### mail.server:blah:secret
### # default entry:
### *:bar:foo

# Because AUTH PLAIN and AUTH LOGIN send the password in clear, we
# only allow these mechanisms over encrypted connections by default.
....
####################################################

And that's the only instructions given in 30_exim4-config_examples,
with respect to client-side authentication.

README.SMTP-AUTH talks about "the appropriate macro as mentioned in the
comments in the configuration file", but the config file
(30_exim4-config_examples) does not mention any macro in its comments.

Note also the circular references: README.SMTP-AUTH says read the
comments in 30_exim4-config_examples, while 30_exim4-config_examples
says read README.SMTP-AUTH for more help.

I think there are two alternative ways to fix this (making clear what
macro needs to be set and removing the circular reference):

1) Keep the reference in README.SMTP-AUTH to the comments in
30_exim4-config_examples, and add those comments. Something like:
# Because AUTH PLAIN and AUTH LOGIN send the password in clear, we
# only allow these mechanisms over encrypted connections by default.
#
# If your ISP does not support encrypted connections, send them an
# email telling them to fix their email server, and then add the following definition:
#	AUTH_CLIENT_ALLOW_NOTLS_PASSWORDS=1
# to <Marc, identify which config file here. Honestly, I don't know in
      which one the definition for AUTH_CLIENT_ALLOW_NOTLS_PASSWORDS should
      be placed>

Or maybe you could place the definition right there in
30_exim4-config_examples, and the instruction will say "...telling them
to fix their email server, and then uncomment the following line" This
would be similar to the instructions you gave in previous versions,
only simpler.

2) Remove the reference to "setting the appropriate macro as mentioned
in the comments in the configuration file" from README.SMTP-AUTH, and
instead say (in README.SMTP-AUTH) something like 

"If you need to enable them for unencrypted connections because your
service provider does support neither TLS encryption nor the CRAM MD5
authentication method, you can do so by placing 
	AUTH_CLIENT_ALLOW_NOTLS_PASSWORDS=1
in <appropriate-config-file>."


I think this documentation issue is in practice quite important, since
I think there are a hell of a lot of ISPs that do not support encrypted
authentication. It would of course be better if they did support it,
but they don't, and we need to be able to deal with this situation with
minimum pain. Of the half-dozen ISPs I've dealt with over the last 5
years or so, I don't think a single one of them has supported encrypted
authentication. I feel a sense of urgency about since we're about to
release sarge, and with exim4 being Debian's default MTA, this question
is going to hit a lot of people.  Lots of newbies... I can read the
code in 30_exim4-config_examples and figure out that
AUTH_CLIENT_ALLOW_NOTLS_PASSWORDS needs to be set.  It's going to be a
lot more difficult for others.

Previously the comments were clear enough "uncomment this line and
comment out those". But in the current version
AUTH_CLIENT_ALLOW_NOTLS_PASSWORDS has gotten itself hidden in the code,
not documented in the comments, which is I think the reverse of what
you want.

I will go now and send an email to my ISP telling them to fix their email server.

Thanks,

Drew