updated smb.conf - have not done a yodl2xxx.

docs/yodldocs/smb.conf.5.yo

@@ -531,6 +531,8 @@ it() link(bf(domain logons))(domainlogons)
 
 it() link(bf(domain master))(domainmaster)
 
+it() link(bf(domain user map))(domainusermap)
+
 it() link(bf(encrypt passwords))(encryptpasswords)
 
 it() link(bf(getwd cache))(getwdcache)
@@ -1810,7 +1812,7 @@ NT users, despite the lack of native support for the NT Security model
 with the NT Domain system and its administration.
 
 This option is used in conjunction with link(bf('local group map'))(localgroupmap)
-and link(bf('username map'))(usernamemap).  The use of these three
+and link(bf('domain user map'))(domainusermap).  The use of these three
 options is trivial and often unnecessary in the case where Samba is
 not expected to interact with any other SAM databases (whether local
 workstations or Domain Controllers).
@@ -1818,7 +1820,9 @@ workstations or Domain Controllers).
 
 The map file is parsed line by line.  If any line begins with a tt('#')
 or a tt(';') then it is ignored.  Each line should contain a single UNIX
-group name on the left then an NT Domain Group name on the right.
+group name on the left then a single NT Domain Group name on the right,
+separated by a tabstop or tt('=').  If either name contains spaces then
+it should be enclosed in quotes.
 The line can be either of the form:
 
 tt(  UNIXgroupname	\\DOMAIN_NAME\\DomainGroupName )
@@ -1833,16 +1837,16 @@ the latter format can be used: the default Domain name is the Samba Server's
 Domain name, specified by link(bf("workgroup = MYGROUP"))(workgroup).
 
 Any UNIX groups that are em(NOT) specified in this map file are assumed
-to be Domain Groups.
+to be Domain Groups, but it depends on the role of the Samba Server.
 
-In this case, when Samba is an bf(EXPERIMENTAL) Domain Controller, Samba
+In the case when Samba is an bf(EXPERIMENTAL) Domain Controller, Samba
 will present em(ALL) such unspecified UNIX groups as its own NT Domain
 Groups, with the same name.
 
 In the case where Samba is member of a domain using
 link(bf("security = domain"))(security), Samba will check the UNIX name with
 its Domain Controller (see link(bf("password server"))(passwordserver))
-as if it was an NT Domain Group.  If the UNIX group is not an NT Group,
+as if it was an NT Domain Group.  If the Domain Controller says that it is not,
 such unspecified (unmapped) UNIX groups which also are not NT Domain
 Groups are treated as Local Groups in the Samba Server's local SAM database.
 NT Administrators will recognise these as Workstation Local Groups,
@@ -1850,14 +1854,31 @@ which are managed by running bf(USRMGR.EXE) and selecting a remote
 Domain named "\\WORKSTATION_NAME", or by running bf(MUSRMGR.EXE) on
 a local Workstation.
 
+This may sound complicated, but it means that a Samba Server as
+either a member of a domain or as an bf(EXPERIMENTAL) Domain Controller
+will act like an NT Workstation (with a local SAM database) or an NT PDC
+(with a Domain SAM database) respectively, without the need for any of
+the map files at all.  If you bf(want) to get fancy, however, you can.
+
 Note that adding an entry to map an arbitrary NT group in an arbitrary
-Domain to an arbitrary UNIX group requires the following: that the UNIX
+Domain to an arbitrary UNIX group em(REQUIRES) the following:
-group exists on the UNIX server; that the NT Domain Group exists in the
+
-specified NT Domain; that the UNIX Server knows about the specified Domain; 
+startit()
-that all the UNIX users (who are expecting to access the Samba
+
+it() that the UNIX group exists on the UNIX server.
+
+it() that the NT Domain Group exists in the specified NT Domain
+
+it() that the UNIX Server knows about the specified Domain; 
+
+it() that all the UNIX users (who are expecting to access the Samba
 Server as the correct NT user and with the correct NT group permissions)
 in the UNIX group be mapped to the correct NT Domain users in the specified
-NT Domain using link(bf('username map'))(usernamemap).
+NT Domain using link(bf('domain user map'))(domainusermap).
+
+Failure to meet any of these requirements may result in either (or
+both) errors reported in the log files or (and) incorrect or missing
+access rights granted to users.
 
 
 label(domaingroups)
@@ -1935,6 +1956,88 @@ and may fail.
   bf(Default:)
 tt(	domain master = no)
 
+
+label(domainusermap)
+dit(bf(domain user map (G)))
+
+This option allows you to specify a file containing unique mappings
+of individual NT Domain User names (in any domain) to UNIX user
+names.  This allows NT domain users to be presented correctly to
+NT systems, despite the lack of native support for the NT Security model
+(based on VAX/VMS) in UNIX.  The reader is advised to become familiar
+with the NT Domain system and its administration.
+
+This option is used in conjunction with link(bf('local group map'))(localgroupmap)
+and link(bf('domain group map'))(domaingroupmap).  The use of these three
+options is trivial and often unnecessary in the case where Samba is
+not expected to interact with any other SAM databases (whether local
+workstations or Domain Controllers).
+
+This option, which provides (and maintains) a one-to-one link between
+UNIX and NT users, is em(DIFFERENT) from link(bf('username map'))
+(usernamemap), which does em(NOT) maintain a distinction between the
+name(s) it can map to and the name it maps.
+
+
+The map file is parsed line by line.  If any line begins with a tt('#')
+or a tt(';') then the line is ignored.  Each line should contain a single UNIX
+user name on the left then a single NT Domain User name on the right,
+separated by a tabstop or tt('=').  If either name contains spaces then
+it should be enclosed in quotes.
+The line can be either of the form:
+
+tt(  UNIXusername	\\DOMAIN_NAME\\DomainUserName )
+
+or:
+
+tt(  UNIXusername	DomainUserName )
+
+In the case where Samba is either an bf(EXPERIMENTAL) Domain Controller
+or it is a member of a domain using link(bf("security = domain"))(security),
+the latter format can be used: the default Domain name is the Samba Server's
+Domain name, specified by link(bf("workgroup = MYGROUP"))(workgroup).
+
+Any UNIX users that are em(NOT) specified in this map file are assumed
+to be either Domain or Workstation Users, depending on the role of the
+Samba Server.
+
+In the case when Samba is an bf(EXPERIMENTAL) Domain Controller, Samba
+will present em(ALL) such unspecified UNIX users as its own NT Domain
+Users, with the same name.
+
+In the case where Samba is member of a domain using
+link(bf("security = domain"))(security), Samba will check the UNIX name with
+its Domain Controller (see link(bf("password server"))(passwordserver))
+as if it was an NT Domain User.  If the Domain Controller says that it is not,
+such unspecified (unmapped) UNIX users which also are not NT Domain
+Users are treated as Local Users in the Samba Server's local SAM database.
+NT Administrators will recognise these as Workstation Users,
+which are managed by running bf(USRMGR.EXE) and selecting a remote
+Domain named "\\WORKSTATION_NAME", or by running bf(MUSRMGR.EXE) on
+a local Workstation.
+
+This may sound complicated, but it means that a Samba Server as
+either a member of a domain or as an bf(EXPERIMENTAL) Domain Controller
+will act like an NT Workstation (with a local SAM database) or an NT PDC
+(with a Domain SAM database) respectively, without the need for any of
+the map files at all.  If you bf(want) to get fancy, however, you can.
+
+Note that adding an entry to map an arbitrary NT User in an arbitrary
+Domain to an arbitrary UNIX user em(REQUIRES) the following:
+
+startit()
+
+it() that the UNIX user exists on the UNIX server.
+
+it() that the NT Domain User exists in the specified NT Domain.
+
+it() that the UNIX Server knows about the specified Domain.
+
+Failure to meet any of these requirements may result in either (or
+both) errors reported in the log files or (and) incorrect or missing
+access rights granted to users.
+
+
 label(dont descend)
 dit(bf(dont descend (S)))
 
@@ -2650,7 +2753,7 @@ NT users, despite the lack of native support for the NT Security model
 with the NT Domain system and its administration.
 
 This option is used in conjunction with link(bf('domain group map'))(domaingroupmap)
-and link(bf('username map'))(usernamemap).  The use of these three
+and link(bf('domain name map'))(domainusermap).  The use of these three
 options is trivial and often unnecessary in the case where Samba
 is not expected to interact with any other SAM databases (whether local
 workstations or Domain Controllers).
@@ -2658,7 +2761,9 @@ workstations or Domain Controllers).
 
 The map file is parsed line by line.  If any line begins with a tt('#')
 or a tt(';') then it is ignored.  Each line should contain a single UNIX
-group name on the left then an NT Local Group name on the right.
+group name on the left then a single NT Local Group name on the right,
+separated by a tabstop or tt('=').  If either name contains spaces then
+it should be enclosed in quotes.
 The line can be either of the form:
 
 tt(  UNIXgroupname	\\DOMAIN_NAME\\LocalGroupName )
@@ -2675,14 +2780,14 @@ Domain name, specified by link(bf("workgroup = MYGROUP"))(workgroup).
 Any UNIX groups that are em(NOT) specified in this map file are treated
 as Local Groups depending on the role of the Samba Server.
 
-When Samba is an bf(EXPERIMENTAL) Domain Controller, Samba
+In the case when Samba is an bf(EXPERIMENTAL) Domain Controller, Samba
 will present em(ALL) unspecified UNIX groups as its own NT Domain
 Groups, with the same name, and em(NOT) as Local Groups.
 
 In the case where Samba is member of a domain using
 link(bf("security = domain"))(security), Samba will check the UNIX name with
 its Domain Controller (see link(bf("password server"))(passwordserver))
-as if it was an NT Domain Group.  If the UNIX group is not an NT Group,
+as if it was an NT Domain Group.  If the Domain Controller says that it is not,
 such unspecified (unmapped) UNIX groups which also are not NT Domain
 Groups are treated as Local Groups in the Samba Server's local SAM database.
 NT Administrators will recognise these as Workstation Local Groups,
@@ -2690,14 +2795,31 @@ which are managed by running bf(USRMGR.EXE) and selecting a remote
 Domain named "\\WORKSTATION_NAME", or by running bf(MUSRMGR.EXE) on
 a local Workstation.
 
+This may sound complicated, but it means that a Samba Server as
+either a member of a domain or as an bf(EXPERIMENTAL) Domain Controller
+will act like an NT Workstation (with a local SAM database) or an NT PDC
+(with a Domain SAM database) respectively, without the need for any of
+the map files at all.  If you bf(want) to get fancy, however, you can.
+
 Note that adding an entry to map an arbitrary NT group in an arbitrary
-Domain to an arbitrary UNIX group requires the following: that the UNIX
+Domain to an arbitrary UNIX group em(REQUIRES) the following:
-group exists on the UNIX server; that the NT Local Group exists in the
+
-specified NT Domain; that the UNIX Server knows about the specified Domain; 
+startit()
-that all the UNIX users (who are expecting to access the Samba
+
+it() that the UNIX group exists on the UNIX server.
+
+it() that the NT Domain Group exists in the specified NT Domain
+
+it() that the UNIX Server knows about the specified Domain; 
+
+it() that all the UNIX users (who are expecting to access the Samba
 Server as the correct NT user and with the correct NT group permissions)
 in the UNIX group be mapped to the correct NT Domain users in the specified
-NT Domain using link(bf('username map'))(usernamemap).
+NT Domain using link(bf('domain user map'))(domainusermap).
+
+Failure to meet any of these requirements may result in either (or
+both) errors reported in the log files or (and) incorrect or missing
+access rights granted to users.
 
 
 label(localmaster)
@@ -5815,6 +5937,17 @@ Windows machines to those that the UNIX box uses. The other is to map
 multiple users to a single username so that they can more easily share
 files.
 
+The use of this option, therefore, relates to UNIX usernames
+and not Windows (specifically NT Domain) usernames.  In other words,
+once a name has been mapped using this option, the Samba server uses
+the mapped name for internal em(AND) external purposes.
+
+This option is em(DIFFERENT) from the link(bf("domain user map"))(domainusermap) 
+parameter, which maintains a one-to-one mapping between UNIX usernames
+and NT Domain Usernames: more specifically, the Samba server maintains
+a link between em(BOTH) usernames, presenting the NT username to the
+external NT world, and using the UNIX username internally.
+
 The map file is parsed line by line. Each line should contain a single
 UNIX username on the left then a tt('=') followed by a list of
 usernames on the right. The list of usernames on the right may contain