docs/smbdotconf/security/security.xml

   1 <samba:parameter name="security"
   2                  context="G"
   3                                  type="enum"
   4                  basic="1" advanced="1" wizard="1" developer="1"
   5                  xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
   6                  <when_value value="security">
   7                          <requires option="encrypted passwords">/(yes|true)/</requires>
   8                  </when_value>
   9 <description>
  10     <para>This option affects how clients respond to
  11     Samba and is one of the most important settings in the <filename moreinfo="none">
  12     smb.conf</filename> file.</para>
  13
  14     <para>The option sets the &quot;security mode bit&quot; in replies to
  15     protocol negotiations with <citerefentry><refentrytitle>smbd</refentrytitle>
  16     <manvolnum>8</manvolnum></citerefentry> to turn share level security on or off. Clients decide
  17     based on this bit whether (and how) to transfer user and password
  18     information to the server.</para>
  19
  20
  21     <para>The default is <command moreinfo="none">security = user</command>, as this is
  22     the most common setting needed when talking to Windows 98 and
  23     Windows NT.</para>
  24
  25     <para>The alternatives are <command moreinfo="none">security = share</command>,
  26     <command moreinfo="none">security = server</command> or <command moreinfo="none">security = domain
  27     </command>.</para>
  28
  29     <para>In versions of Samba prior to 2.0.0, the default was
  30     <command moreinfo="none">security = share</command> mainly because that was
  31     the only option at one stage.</para>
  32
  33     <para>There is a bug in WfWg that has relevance to this
  34     setting. When in user or server level security a WfWg client
  35     will totally ignore the username and password you type in the &quot;connect
  36     drive&quot; dialog box. This makes it very difficult (if not impossible)
  37     to connect to a Samba service as anyone except the user that
  38     you are logged into WfWg as.</para>
  39
  40     <para>If your PCs use usernames that are the same as their
  41     usernames on the UNIX machine then you will want to use
  42     <command moreinfo="none">security = user</command>. If you mostly use usernames
  43     that don't exist on the UNIX box then use <command moreinfo="none">security =
  44     share</command>.</para>
  45
  46     <para>You should also use <command moreinfo="none">security = share</command> if you
  47     want to mainly setup shares without a password (guest shares). This
  48     is commonly used for a shared printer server. It is more difficult
  49     to setup guest shares with <command moreinfo="none">security = user</command>, see
  50     the <smbconfoption name="map to guest"/>parameter for details.</para>
  51
  52     <para>It is possible to use <command moreinfo="none">smbd</command> in a <emphasis>
  53     hybrid mode</emphasis> where it is offers both user and share
  54     level security under different <smbconfoption name="NetBIOS aliases"/>. </para>
  55
  56     <para>The different settings will now be explained.</para>
  57
  58
  59     <para><anchor id="SECURITYEQUALSSHARE"/><emphasis>SECURITY = SHARE</emphasis></para>
  60
  61     <para>When clients connect to a share level security server they
  62     need not log onto the server with a valid username and password before
  63     attempting to connect to a shared resource (although modern clients
  64     such as Windows 95/98 and Windows NT will send a logon request with
  65     a username but no password when talking to a <command moreinfo="none">security = share
  66     </command> server). Instead, the clients send authentication information
  67     (passwords) on a per-share basis, at the time they attempt to connect
  68     to that share.</para>
  69
  70     <para>Note that <command moreinfo="none">smbd</command> <emphasis>ALWAYS</emphasis>
  71     uses a valid UNIX user to act on behalf of the client, even in
  72     <command moreinfo="none">security = share</command> level security.</para>
  73
  74     <para>As clients are not required to send a username to the server
  75     in share level security, <command moreinfo="none">smbd</command> uses several
  76     techniques to determine the correct UNIX user to use on behalf
  77     of the client.</para>
  78
  79     <para>A list of possible UNIX usernames to match with the given
  80     client password is constructed using the following methods :</para>
  81
  82     <itemizedlist>
  83         <listitem>
  84             <para>If the <smbconfoption name="guest only"/> parameter is set, then all the other
  85             stages are missed and only the <smbconfoption name="guest account"/> username is checked.
  86             </para>
  87         </listitem>
  88
  89         <listitem>
  90             <para>Is a username is sent with the share connection
  91             request, then this username (after mapping - see <smbconfoption name="username map"/>),
  92             is added as a potential username.
  93             </para>
  94         </listitem>
  95
  96         <listitem>
  97             <para>If the client did a previous <emphasis>logon
  98             </emphasis> request (the SessionSetup SMB call) then the
  99             username sent in this SMB will be added as a potential username.
 100             </para>
 101         </listitem>
 102
 103         <listitem>
 104             <para>The name of the service the client requested is
 105             added as a potential username.
 106             </para>
 107         </listitem>
 108
 109         <listitem>
 110             <para>The NetBIOS name of the client is added to
 111             the list as a potential username.
 112             </para>
 113         </listitem>
 114
 115         <listitem>
 116             <para>Any users on the <smbconfoption name="user"/> list are added as potential usernames.
 117             </para>
 118         </listitem>
 119     </itemizedlist>
 120
 121     <para>If the <parameter moreinfo="none">guest only</parameter> parameter is
 122     not set, then this list is then tried with the supplied password.
 123     The first user for whom the password matches will be used as the
 124     UNIX user.</para>
 125
 126     <para>If the <parameter moreinfo="none">guest only</parameter> parameter is
 127     set, or no username can be determined then if the share is marked
 128     as available to the <parameter moreinfo="none">guest account</parameter>, then this
 129     guest user will be used, otherwise access is denied.</para>
 130
 131     <para>Note that it can be <emphasis>very</emphasis> confusing
 132     in share-level security as to which UNIX username will eventually
 133     be used in granting access.</para>
 134
 135     <para>See also the section <link linkend="VALIDATIONSECT">
 136     NOTE ABOUT USERNAME/PASSWORD VALIDATION</link>.</para>
 137
 138     <para><anchor id="SECURITYEQUALSUSER"/><emphasis>SECURITY = USER</emphasis></para>
 139
 140     <para>This is the default security setting in Samba 3.0.
 141     With user-level security a client must first &quot;log-on&quot; with a
 142     valid username and password (which can be mapped using the <smbconfoption name="username map"/>
 143     parameter). Encrypted passwords (see the <smbconfoption name="encrypted passwords"/> parameter) can also
 144     be used in this security mode. Parameters such as <smbconfoption name="user"/> and <smbconfoption
 145         name="guest only"/> if set      are then applied and
 146     may change the UNIX user to use on this connection, but only after
 147     the user has been successfully authenticated.</para>
 148
 149     <para><emphasis>Note</emphasis> that the name of the resource being
 150     requested is <emphasis>not</emphasis> sent to the server until after
 151     the server has successfully authenticated the client. This is why
 152     guest shares don't work in user level security without allowing
 153     the server to automatically map unknown users into the <smbconfoption name="guest account"/>.
 154     See the <smbconfoption name="map to guest"/> parameter for details on doing this.</para>
 155
 156     <para>See also the section <link linkend="VALIDATIONSECT">NOTE ABOUT USERNAME/PASSWORD VALIDATION</link>.</para>
 157
 158     <para><anchor id="SECURITYEQUALSDOMAIN"/><emphasis>SECURITY = DOMAIN</emphasis></para>
 159
 160     <para>This mode will only work correctly if <citerefentry><refentrytitle>net</refentrytitle>
 161     <manvolnum>8</manvolnum></citerefentry> has been used to add this
 162     machine into a Windows NT Domain. It expects the <smbconfoption name="encrypted passwords"/>
 163         parameter to be set to <constant>yes</constant>. In this
 164     mode Samba will try to validate the username/password by passing
 165     it to a Windows NT Primary or Backup Domain Controller, in exactly
 166     the same way that a Windows NT Server would do.</para>
 167
 168     <para><emphasis>Note</emphasis> that a valid UNIX user must still
 169     exist as well as the account on the Domain Controller to allow
 170     Samba to have a valid UNIX account to map file access to.</para>
 171
 172     <para><emphasis>Note</emphasis> that from the client's point
 173     of view <command moreinfo="none">security = domain</command> is the same
 174     as <command moreinfo="none">security = user</command>. It only
 175     affects how the server deals with the authentication,
 176     it does not in any way affect what the client sees.</para>
 177
 178     <para><emphasis>Note</emphasis> that the name of the resource being
 179     requested is <emphasis>not</emphasis> sent to the server until after
 180     the server has successfully authenticated the client. This is why
 181     guest shares don't work in user level security without allowing
 182     the server to automatically map unknown users into the <smbconfoption name="guest account"/>.
 183     See the <smbconfoption name="map to guest"/> parameter for details on doing this.</para>
 184
 185     <para>See also the section <link linkend="VALIDATIONSECT">
 186     NOTE ABOUT USERNAME/PASSWORD VALIDATION</link>.</para>
 187
 188     <para>See also the <smbconfoption name="password server"/> parameter and
 189          the <smbconfoption name="encrypted passwords"/> parameter.</para>
 190
 191     <para><anchor id="SECURITYEQUALSSERVER"/><emphasis>SECURITY = SERVER</emphasis></para>
 192
 193     <para>
 194         In this mode Samba will try to validate the username/password by passing it to another SMB server, such as an
 195         NT box. If this fails it will revert to <command moreinfo="none">security = user</command>. It expects the
 196         <smbconfoption name="encrypted passwords"/> parameter to be set to <constant>yes</constant>, unless the remote
 197         server does not support them.  However note that if encrypted passwords have been negotiated then Samba cannot
 198         revert back to checking the UNIX password file, it must have a valid <filename
 199         moreinfo="none">smbpasswd</filename> file to check users against. See the chapter about the User Database in
 200         the Samba HOWTO Collection for details on how to set this up.
 201 </para>
 202
 203         <note><para>This mode of operation has
 204     significant pitfalls since it is more vulnerable to
 205     man-in-the-middle attacks and server impersonation.  In particular,
 206     this mode of operation can cause significant resource consuption on
 207     the PDC, as it must maintain an active connection for the duration
 208     of the user's session.  Furthermore, if this connection is lost,
 209     there is no way to reestablish it, and futher authentications to the
 210     Samba server may fail (from a single client, till it disconnects).
 211         </para></note>
 212
 213         <note><para>From the client's point of
 214     view <command moreinfo="none">security = server</command> is the
 215     same as <command moreinfo="none">security = user</command>.  It
 216     only affects how the server deals  with the authentication, it does
 217         not in any way affect what the  client sees.</para></note>
 218
 219     <para><emphasis>Note</emphasis> that the name of the resource being
 220     requested is <emphasis>not</emphasis> sent to the server until after
 221     the server has successfully authenticated the client. This is why
 222     guest shares don't work in user level security without allowing
 223     the server to automatically map unknown users into the <smbconfoption name="guest account"/>.
 224     See the <smbconfoption name="map to guest"/> parameter for details on doing this.</para>
 225
 226     <para>See also the section <link linkend="VALIDATIONSECT">
 227     NOTE ABOUT USERNAME/PASSWORD VALIDATION</link>.</para>
 228
 229     <para>See also the <smbconfoption name="password server"/> parameter and the
 230         <smbconfoption name="encrypted passwords"/> parameter.</para>
 231
 232         <para><anchor id="SECURITYEQUALSADS"/><emphasis>SECURITY = ADS</emphasis></para>
 233
 234         <para>In this mode, Samba will act as a domain member in an ADS realm. To operate
 235                 in this mode, the machine running Samba will need to have Kerberos installed
 236                 and configured and Samba will need to be joined to the ADS realm using the
 237                 net utility. </para>
 238
 239         <para>Note that this mode does NOT make Samba operate as a Active Directory Domain
 240                 Controller. </para>
 241
 242         <para>Read the chapter about Domain Membership in the HOWTO for details.</para>
 243 </description>
 244
 245 <related>realm</related>
 246 <related>encrypt passwords</related>
 247
 248 <value type="default">USER</value>
 249 <value type="example">DOMAIN</value>
 250 </samba:parameter>