--- login_ldap.8.orig	Thu Feb  7 16:56:28 2008
+++ login_ldap.8	Tue Oct 27 12:40:53 2015
@@ -39,7 +39,7 @@
 .Os
 .Sh NAME
 .Nm login_ldap
-.Nd contact ldap directory server for authentication
+.Nd contact LDAP directory server for authentication
 .Sh SYNOPSIS
 .Nm login_ldap
 .Op Fl s Ar service
@@ -88,30 +88,32 @@ This option and its value are ignored.
 The
 .Nm 
 utility will perform up to two searches on the LDAP server to
-authenticate the user. 
-The first pass occurs for all users to be authenticated with 
-this utility, and searches for the given username in the section 
+identify the user's DN, and will then attempt to bind using the
+supplied password.
+.Pp
+The first pass occurs for all users to be authenticated with
+this utility, and searches for the given username in the section
 given by the specified basedn (see below).
-The second pass occurs only if values for x-ldap-groupdn and 
-x-ldap-groupfilter are present in login.conf. 
-This second pass will check that the user is present in the section 
-of the directory represented by x-ldap-groupdn, according to the 
+The second pass occurs only if values for x-ldap-groupdn and
+x-ldap-groupfilter are present in login.conf.
+This second pass will check that the user is present in the section
+of the directory represented by x-ldap-groupdn, according to the
 specification of x-ldap-groupfilter.
 .Pp
 .Sh LOGIN.CONF VARIABLES
 The
 .Nm
-utility requires the following ldap-specific
+utility requires the following LDAP-specific
 .Xr login.conf 5
 variables:
 .Bl -tag -width x-ldap-filter
-.\" some of thess are not really required, and can be set in the ldap library conf
+.\" some of these are not really required, and can be set in the LDAP library conf
 .\" but say it's required as its nasty not to specify it
 .It x-ldap-server
 Hostname or IP Adress of the primary server to contact for authorization
 requests. See SERVER FORMATS for details.
 .It x-ldap-basedn
-Point in the ldap servers Directory Information Tree 
+Point in the LDAP server's Directory Information Tree
 .Nm
 should begin searching for user objects.
 .El
@@ -251,26 +253,25 @@ it defaults to 389, if the mode is 'ssl' it defaults t
 .Pp
 The SSL/TLS mode is one of: 
 .Bl -tag -width starttls
-.It plain
-No attempt will made to use SSL or TLS
 .It starttls
-Once a connection to the server has been established, a StartTLS request will
-be made.
+Connect to the standard port, send a StartTLS request, and negotiate SSL/TLS.
 .It ssl
-SSL will be required for the connection.
+Connect to the "ssl-wrapped" port, negotiate SSL/TLS.
+.It plain
+INSECURE - no attempt will made to use SSL/TLS.
 .El
 .Pp
-The version is an integer, either 1, 2 or 3. 
-The default is to use version 3.
+The version is an integer, either 1, 2 or 3.
+The default is to use LDAP version 3.
 .Pp
 Apart from the hostname, options may be left out or left blank.
 For example, the following would result in SSL being used on port 636, with
-version 3
+LDAPv3:
 .Pp
 x-ldap-server=foo.ifost.org.au,,ssl
 .Pp
-Similarly, the following would result in a connection to the host using on
-port 389 with no SSL/TLS.
+Similarly, the following would result in an insecure connection to the host
+on port 389:
 .Pp
 x-ldap-server=bar.ifost.org.au
 .Pp
@@ -280,6 +281,7 @@ For more examples, please see the following files.
 .Bl -tag -compact -width x-ldap-groupfilter
 .It Pa /usr/local/share/examples/login_ldap/login_ldap.conf
 .It Pa /usr/local/share/examples/login_ldap/active-directory.login_ldap.conf
+.El
 .Sh FILES
 .Bl -tag -compact -width x-ldap-groupfilter
 .It Pa /etc/login.conf
@@ -300,24 +302,22 @@ Raul Aldaz <raul.aldaz@grupocarreras.com>
 .Pp
 Please contact Michael Erdely with any issues relating to the port.
 .Sh CAVEATS
+As there is no SASL support, passwords are sent to the LDAP server.
+TLS should be used to protect the password in transit.
+.Pp
 As of version 3.4 the default scope is sub, which is what most
 people want. 
 .Pp
 There have been some significant changes to the login.conf variables,
 in particular how servers are specified.
 .Pp
-There is no SASL support. This should be present in the next version,
-but when the next version is done is anyone's guess.
-.Pp
-.Ox
-does not ship with an ldap server in the default install, however
-OpenLDAP is available via
-.Xr packages 7 .
-.Pp
-Until
-.Ox
-gets an nsswitch implementation or something similar, every user in the LDAP server
-will need to have a valid passwd file entry. This can be achieved by using the
+.Nm
+does not provide user account maps, only authentication services.
+User accounts may be handled either via
+.Xr ypldap 8
+or by static entries in the
+.Xr passwd 5
+file (e.g. by using
 .Xr useradd 8
-utility with similar arguments to this:
-useradd -m -d /home/peterw -s /bin/sh -L ldap peterw
+with arguments like this:
+useradd -m -d /home/peterw -s /bin/sh -L ldap peterw).
