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