1 <samba:parameter name="username map"
3 advanced="1" developer="1"
5 xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
7 <para>This option allows you to specify a file containing
8 a mapping of usernames from the clients to the server. This can be
9 used for several purposes. The most common is to map usernames
10 that users use on DOS or Windows machines to those that the UNIX
11 box uses. The other is to map multiple users to a single username
12 so that they can more easily share files.</para>
14 <para>Please note that for user or share mode security, the
15 username map is applied prior to validating the user credentials.
16 Domain member servers (domain or ads) apply the username map
17 after the user has been successfully authenticated by the domain
18 controller and require fully qualified enties in the map table
19 (e.g. biddle = DOMAIN\foo).</para>
21 <para>The map file is parsed line by line. Each line should
22 contain a single UNIX username on the left then a '=' followed
23 by a list of usernames on the right. The list of usernames on the
24 right may contain names of the form @group in which case they
25 will match any UNIX username in that group. The special client
26 name '*' is a wildcard and matches any name. Each line of the
27 map file may be up to 1023 characters long.</para>
29 <para>The file is processed on each line by taking the
30 supplied username and comparing it with each username on the right
31 hand side of the '=' signs. If the supplied name matches any of
32 the names on the right hand side then it is replaced with the name
33 on the left. Processing then continues with the next line.</para>
35 <para>If any line begins with a '#' or a ';' then it is ignored</para>
37 <para>If any line begins with an '!' then the processing
38 will stop after that line if a mapping was done by the line.
39 Otherwise mapping continues with every line being processed.
40 Using '!' is most useful when you have a wildcard mapping line
41 later in the file.</para>
43 <para>For example to map from the name <constant>admin</constant>
44 or <constant>administrator</constant> to the UNIX name <constant>
45 root</constant> you would use:</para>
47 <para><command moreinfo="none">root = admin administrator</command></para>
49 <para>Or to map anyone in the UNIX group <constant>system</constant>
50 to the UNIX name <constant>sys</constant> you would use:</para>
52 <para><command moreinfo="none">sys = @system</command></para>
54 <para>You can have as many mappings as you like in a username map file.</para>
57 <para>If your system supports the NIS NETGROUP option then
58 the netgroup database is checked before the <filename moreinfo="none">/etc/group
59 </filename> database for matching groups.</para>
61 <para>You can map Windows usernames that have spaces in them
62 by using double quotes around the name. For example:</para>
64 <para><command moreinfo="none">tridge = "Andrew Tridgell"</command></para>
66 <para>would map the windows username "Andrew Tridgell" to the
67 unix username "tridge".</para>
69 <para>The following example would map mary and fred to the
70 unix user sys, and map the rest to guest. Note the use of the
71 '!' to tell Samba to stop processing if it gets a match on
74 <para><programlisting format="linespecific">
77 </programlisting></para>
80 Note that the remapping is applied to all occurrences
81 of usernames. Thus if you connect to \\server\fred and <constant>
82 fred</constant> is remapped to <constant>mary</constant> then you
83 will actually be connecting to \\server\mary and will need to
84 supply a password suitable for <constant>mary</constant> not
85 <constant>fred</constant>. The only exception to this is the
86 username passed to the <smbconfoption name="password server"/>
87 (if you have one). The password server will receive whatever
88 username the client supplies without modification.
91 <para>Also note that no reverse mapping is done. The main effect
92 this has is with printing. Users who have been mapped may have
93 trouble deleting print jobs as PrintManager under WfWg will think
94 they don't own the print job.</para>
97 Samba versions prior to 3.0.8 would only support reading the fully qualified
98 username (e.g.: DOMAIN\user) from the username map when performing a
99 kerberos login from a client. However, when looking up a map
100 entry for a user authenticated by NTLM[SSP], only the login name would be
101 used for matches. This resulted in inconsistent behavior sometimes
102 even on the same server.
106 The following functionality is obeyed in version 3.0.8 and later:
110 When performing local authentication, the username map is
111 applied to the login name before attempting to authenticate
116 When relying upon a external domain controller for validating
117 authentication requests, smbd will apply the username map
118 to the fully qualified username (i.e. DOMAIN\user) only
119 after the user has been successfully authenticated.
123 An example of use is:
125 username map = /usr/local/samba/lib/users.map
130 <value type="default"><comment>no username map</comment></value>