1 <samba:parameter name="security"
3 basic="1" advanced="1" wizard="1" developer="1"
4 xmlns:samba="http://samba.org/common">
6 <para>This option affects how clients respond to
7 Samba and is one of the most important settings in the <filename moreinfo="none">
8 smb.conf</filename> file.</para>
10 <para>The option sets the "security mode bit" in replies to
11 protocol negotiations with <citerefentry><refentrytitle>smbd</refentrytitle>
12 <manvolnum>8</manvolnum></citerefentry> to turn share level security on or off. Clients decide
13 based on this bit whether (and how) to transfer user and password
14 information to the server.</para>
17 <para>The default is <command moreinfo="none">security = user</command>, as this is
18 the most common setting needed when talking to Windows 98 and
21 <para>The alternatives are <command moreinfo="none">security = share</command>,
22 <command moreinfo="none">security = server</command> or <command moreinfo="none">security = domain
25 <para>In versions of Samba prior to 2.0.0, the default was
26 <command moreinfo="none">security = share</command> mainly because that was
27 the only option at one stage.</para>
29 <para>There is a bug in WfWg that has relevance to this
30 setting. When in user or server level security a WfWg client
31 will totally ignore the password you type in the "connect
32 drive" dialog box. This makes it very difficult (if not impossible)
33 to connect to a Samba service as anyone except the user that
34 you are logged into WfWg as.</para>
36 <para>If your PCs use usernames that are the same as their
37 usernames on the UNIX machine then you will want to use
38 <command moreinfo="none">security = user</command>. If you mostly use usernames
39 that don't exist on the UNIX box then use <command moreinfo="none">security =
40 share</command>.</para>
42 <para>You should also use <command moreinfo="none">security = share</command> if you
43 want to mainly setup shares without a password (guest shares). This
44 is commonly used for a shared printer server. It is more difficult
45 to setup guest shares with <command moreinfo="none">security = user</command>, see
46 the <link linkend="MAPTOGUEST"><parameter moreinfo="none">map to guest</parameter>
47 </link>parameter for details.</para>
49 <para>It is possible to use <command moreinfo="none">smbd</command> in a <emphasis>
50 hybrid mode</emphasis> where it is offers both user and share
51 level security under different <link linkend="NETBIOSALIASES">
52 <parameter moreinfo="none">NetBIOS aliases</parameter></link>. </para>
54 <para>The different settings will now be explained.</para>
57 <para><anchor id="SECURITYEQUALSSHARE"/><emphasis>SECURITY = SHARE</emphasis></para>
59 <para>When clients connect to a share level security server they
60 need not log onto the server with a valid username and password before
61 attempting to connect to a shared resource (although modern clients
62 such as Windows 95/98 and Windows NT will send a logon request with
63 a username but no password when talking to a <command moreinfo="none">security = share
64 </command> server). Instead, the clients send authentication information
65 (passwords) on a per-share basis, at the time they attempt to connect
68 <para>Note that <command moreinfo="none">smbd</command> <emphasis>ALWAYS</emphasis>
69 uses a valid UNIX user to act on behalf of the client, even in
70 <command moreinfo="none">security = share</command> level security.</para>
72 <para>As clients are not required to send a username to the server
73 in share level security, <command moreinfo="none">smbd</command> uses several
74 techniques to determine the correct UNIX user to use on behalf
77 <para>A list of possible UNIX usernames to match with the given
78 client password is constructed using the following methods :</para>
82 <para>If the <link linkend="GUESTONLY"><parameter moreinfo="none">guest
83 only</parameter></link> parameter is set, then all the other
84 stages are missed and only the <link linkend="GUESTACCOUNT">
85 <parameter moreinfo="none">guest account</parameter></link> username is checked.
90 <para>Is a username is sent with the share connection
91 request, then this username (after mapping - see <link linkend="USERNAMEMAP">
92 <parameter moreinfo="none">username map</parameter></link>),
93 is added as a potential username.
98 <para>If the client did a previous <emphasis>logon
99 </emphasis> request (the SessionSetup SMB call) then the
100 username sent in this SMB will be added as a potential username.
105 <para>The name of the service the client requested is
106 added as a potential username.
111 <para>The NetBIOS name of the client is added to
112 the list as a potential username.
117 <para>Any users on the <link linkend="USER"><parameter moreinfo="none">
118 user</parameter></link> list are added as potential usernames.
123 <para>If the <parameter moreinfo="none">guest only</parameter> parameter is
124 not set, then this list is then tried with the supplied password.
125 The first user for whom the password matches will be used as the
128 <para>If the <parameter moreinfo="none">guest only</parameter> parameter is
129 set, or no username can be determined then if the share is marked
130 as available to the <parameter moreinfo="none">guest account</parameter>, then this
131 guest user will be used, otherwise access is denied.</para>
133 <para>Note that it can be <emphasis>very</emphasis> confusing
134 in share-level security as to which UNIX username will eventually
135 be used in granting access.</para>
137 <para>See also the section <link linkend="VALIDATIONSECT">
138 NOTE ABOUT USERNAME/PASSWORD VALIDATION</link>.</para>
140 <para><anchor id="SECURITYEQUALSUSER"/><emphasis>SECURITY = USER</emphasis></para>
142 <para>This is the default security setting in Samba 3.0.
143 With user-level security a client must first "log-on" with a
144 valid username and password (which can be mapped using the <link linkend="USERNAMEMAP">
145 <parameter moreinfo="none">username map</parameter></link>
146 parameter). Encrypted passwords (see the <link linkend="ENCRYPTPASSWORDS">
147 <parameter moreinfo="none">encrypted passwords</parameter></link> parameter) can also
148 be used in this security mode. Parameters such as <link linkend="USER">
149 <parameter moreinfo="none">user</parameter></link> and <link linkend="GUESTONLY">
150 <parameter moreinfo="none">guest only</parameter></link> if set are then applied and
151 may change the UNIX user to use on this connection, but only after
152 the user has been successfully authenticated.</para>
154 <para><emphasis>Note</emphasis> that the name of the resource being
155 requested is <emphasis>not</emphasis> sent to the server until after
156 the server has successfully authenticated the client. This is why
157 guest shares don't work in user level security without allowing
158 the server to automatically map unknown users into the <link linkend="GUESTACCOUNT">
159 <parameter moreinfo="none">guest account</parameter></link>.
160 See the <link linkend="MAPTOGUEST"><parameter moreinfo="none">map to guest</parameter>
161 </link> parameter for details on doing this.</para>
163 <para>See also the section <link linkend="VALIDATIONSECT">
164 NOTE ABOUT USERNAME/PASSWORD VALIDATION</link>.</para>
166 <para><anchor id="SECURITYEQUALSDOMAIN"/><emphasis>SECURITY = DOMAIN</emphasis></para>
168 <para>This mode will only work correctly if <citerefentry><refentrytitle>net</refentrytitle>
169 <manvolnum>8</manvolnum></citerefentry> has been used to add this
170 machine into a Windows NT Domain. It expects the <link linkend="ENCRYPTPASSWORDS">
171 <parameter moreinfo="none">encrypted passwords</parameter>
172 </link> parameter to be set to <constant>yes</constant>. In this
173 mode Samba will try to validate the username/password by passing
174 it to a Windows NT Primary or Backup Domain Controller, in exactly
175 the same way that a Windows NT Server would do.</para>
177 <para><emphasis>Note</emphasis> that a valid UNIX user must still
178 exist as well as the account on the Domain Controller to allow
179 Samba to have a valid UNIX account to map file access to.</para>
181 <para><emphasis>Note</emphasis> that from the client's point
182 of view <command moreinfo="none">security = domain</command> is the same
183 as <command moreinfo="none">security = user</command>. It only
184 affects how the server deals with the authentication,
185 it does not in any way affect what the client sees.</para>
187 <para><emphasis>Note</emphasis> that the name of the resource being
188 requested is <emphasis>not</emphasis> sent to the server until after
189 the server has successfully authenticated the client. This is why
190 guest shares don't work in user level security without allowing
191 the server to automatically map unknown users into the <link linkend="GUESTACCOUNT">
192 <parameter moreinfo="none">guest account</parameter></link>.
193 See the <link linkend="MAPTOGUEST"><parameter moreinfo="none">map to guest</parameter>
194 </link> parameter for details on doing this.</para>
196 <para>See also the section <link linkend="VALIDATIONSECT">
197 NOTE ABOUT USERNAME/PASSWORD VALIDATION</link>.</para>
199 <para>See also the <link linkend="PASSWORDSERVER"><parameter moreinfo="none">password
200 server</parameter></link> parameter and the <link linkend="ENCRYPTPASSWORDS">
201 <parameter moreinfo="none">encrypted passwords</parameter>
202 </link> parameter.</para>
204 <para><anchor id="SECURITYEQUALSSERVER"/><emphasis>SECURITY = SERVER</emphasis></para>
206 <para>In this mode Samba will try to validate the username/password
207 by passing it to another SMB server, such as an NT box. If this
208 fails it will revert to <command moreinfo="none">security =
209 user</command>. It expects the <link linkend="ENCRYPTPASSWORDS">
210 <parameter moreinfo="none">encrypted passwords</parameter></link> parameter
211 to be set to <constant>yes</constant>, unless the remote server
212 does not support them. However note that if encrypted passwords have been
213 negotiated then Samba cannot revert back to checking the UNIX password file,
214 it must have a valid <filename moreinfo="none">smbpasswd</filename> file to check
215 users against. See the documentation file in the <filename moreinfo="none">docs/</filename> directory
216 <filename moreinfo="none">ENCRYPTION.txt</filename> for details on how to set this up.</para>
218 <para><emphasis>Note</emphasis> this mode of operation has
219 significant pitfalls, due to the fact that is activly initiates a
220 man-in-the-middle attack on the remote SMB server. In particular,
221 this mode of operation can cause significant resource consuption on
222 the PDC, as it must maintain an active connection for the duration
223 of the user's session. Furthermore, if this connection is lost,
224 there is no way to reestablish it, and futher authenticaions to the
225 Samba server may fail. (From a single client, till it disconnects).
228 <para><emphasis>Note</emphasis> that from the client's point of
229 view <command moreinfo="none">security = server</command> is the
230 same as <command moreinfo="none">security = user</command>. It
231 only affects how the server deals with the authentication, it does
232 not in any way affect what the client sees.</para>
234 <para><emphasis>Note</emphasis> that the name of the resource being
235 requested is <emphasis>not</emphasis> sent to the server until after
236 the server has successfully authenticated the client. This is why
237 guest shares don't work in user level security without allowing
238 the server to automatically map unknown users into the <link linkend="GUESTACCOUNT">
239 <parameter moreinfo="none">guest account</parameter></link>.
240 See the <link linkend="MAPTOGUEST"><parameter moreinfo="none">map to guest</parameter>
241 </link> parameter for details on doing this.</para>
243 <para>See also the section <link linkend="VALIDATIONSECT">
244 NOTE ABOUT USERNAME/PASSWORD VALIDATION</link>.</para>
246 <para>See also the <link linkend="PASSWORDSERVER"><parameter moreinfo="none">password
247 server</parameter></link> parameter and the <link linkend="ENCRYPTPASSWORDS">
248 <parameter moreinfo="none">encrypted passwords</parameter></link> parameter.</para>
250 <para>Default: <command moreinfo="none">security = USER</command></para>
251 <para>Example: <command moreinfo="none">security = DOMAIN</command></para>