A username map is a mechanism for translating a login name sent by a client in the session setup request to a local Unix username. It’s independent of any passdb backend. The most common use is to handle usernames that differ between Windows and Unix. Usernames on Windows systems can violate the limits placed by Unix systems on length and characters used, so sometimes the user account must be stored on the Unix or Linux system, and recognized by Samba as a different name from the one sent by a Windows system to authenticate the user.

This mapping feature comes in two forms: username map uses a file lookup, whereas username map script relies upon an external command to perform the search. Both smb.conf parameters are summarized in Table 5-11.

Table 5-11. Username mapping

Parameter	Value	Description	Default	Scope
username map	string	Absolute path of the username map file.	""	Global
username map script	string	Absolute path to a script or tool that accepts the requested username as a parameter and prints the mapped username (if any) to standard output. This script is mutually exclusive with, and takes precedence over, the username map parameter.	""	Global

The username map option requires the absolute path to a map file on the server. Frequently this file is named smbusers and is stored in the same location as smb.conf. No default mapping file is distributed with Samba, although some vendors may choose to do so. The username map option must be explicitly set as shown here:

  [global ]
      username map = /usr/local/samba/lib/smbusers

This map file contains entries in the form of:

  map_to = map_from

The map_to  value is a single Unix username. The map_from  value may be a list of val ues that include:

1. A single username. Login names containing whitespace must be surrounded by double quotes (e.g., “Lee Zard”).
   
2. A Unix or NIS netgroup name prefaced by a & , @ , or + . This same syntax is reused for other smb.conf parameters and so is discussed in the final section of this chapter, where it is most applicable.
   
3. A single wildcard character, *, that matches everything.

Processing of the username map file continues until either the complete map has been parsed or until an entry prefixed by an exclamation point ( ! ) matches successfully. Any lines beginning with a hash ( # ) or semicolon ( ; ) character are ignored as comments. If no match is found at all, the original username is unchanged.

As an example, to map a Windows user of Lee.Zard to a Unix login name of lizard, we could use a single entry such as:

  !lizard = Lee.Zard

The righthand values are compared in a case-insensitive fashion, so this example would succeed regardless of whether the user logs on with Lee.Zard or LEE.ZARD. The beginning ! prevents smbd from continuing to look for additional matches for lizard after this entry is parsed.

The username map script allows an administrator to define an external command that will be invoked, rather than reading a map file directly. It provides the flexibility to store the maps in directory services such as LDAP. The mapping command must accept a username as its sole parameter (provided by smbd) and must return a single login name to standard output if any mapping is necessary. Without getting into too many details, the following example uses the OpenLDAP ldapsearch tool to query a directory service based on the common name ( cn ) attribute and maps the user to the login name provided by the uid attribute.

  #!/bin/sh
  ldapsearch -x -LLL -h ldapsrv1 -b "dc=example,dc=com" \
    -s sub "(&(cn=$1)(objectclass=posixAccount))" \|
    grep uid: | cut -d: -f 2 | sed 's/^\s*//'

Assuming that this script is named ldapmapuser.sh, we can instruct smbd to make use of it by adding the following line to smb.conf:

  [global ]
      username map script = /usr/local/bin/ldapmapuser.sh

In this way, it is possible to integrate the username map functionality with the ldapsam passdb backend.

The point at which the mapping occurs is dependent on the value of the security parameter. In the context of our current discussion around security = user , the map is queried before the user is authenticated. To illustrate the consequence, assume that we have the following entry in a username map file:

  root = administrator

If a user attempts to connect to our standalone server with a login name of Administrator, the password supplied must match the one for root in Samba’s configured passdb backend.

When Samba is configured as a domain member server ( security = domain or security = ads ), the map is applied after a user has been authenticated by a domain controller. The means that when a user connects as DOMAIN\administrator, she must provide the actual password for that account even though the account may be eventually mapped to the local superuser account. The process becomes even more complicated with the presence of winbindd. Therefore the remainder of the discussion of username maps and member servers is saved until Chapter 10.