docs-xml/smbdotconf/security/usernamemap.xml

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