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