summaryrefslogtreecommitdiff
path: root/docs-xml/smbdotconf/security/security.xml
blob: 55e147e8dc4adc57d3ee829ab297e3e068ec4a54 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
<samba:parameter name="security"
                 context="G"
				 type="enum"
                 basic="1" advanced="1" wizard="1" developer="1"
		 xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
		 <when_value value="security">
			 <requires option="encrypted passwords">/(yes|true)/</requires>
		 </when_value>
<description>
    <para>This option affects how clients respond to 
    Samba and is one of the most important settings in the <filename moreinfo="none">
    smb.conf</filename> file.</para>

    <para>The option sets the &quot;security mode bit&quot; in replies to 
    protocol negotiations with <citerefentry><refentrytitle>smbd</refentrytitle>
    <manvolnum>8</manvolnum></citerefentry> to turn share level security on or off. Clients decide 
    based on this bit whether (and how) to transfer user and password 
    information to the server.</para>


    <para>The default is <command moreinfo="none">security = user</command>, as this is
    the most common setting needed when talking to Windows 98 and 
    Windows NT.</para>

    <para>The alternatives are
    <command moreinfo="none">security = ads</command> or <command moreinfo="none">security = domain
    </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>

    <para>In versions of Samba prior to 2.0.0, the default was 
    <command moreinfo="none">security = share</command> mainly because that was
    the only option at one stage.</para>

    <para>You should use <command moreinfo="none">security = user</command> and 
    <smbconfoption name="map to guest"/> if you 
    want to mainly setup shares without a password (guest shares). This 
    is commonly used for a shared printer server. </para>
		
    <para>It is possible to use <command moreinfo="none">smbd</command> in a <emphasis>
    hybrid mode</emphasis> where it is offers both user and share 
    level security under different <smbconfoption name="NetBIOS aliases"/>. </para>

    <para>The different settings will now be explained.</para>


    <para><anchor id="SECURITYEQUALSUSER"/><emphasis>SECURITY = USER</emphasis></para>

    <para>This is the default security setting in Samba. 
    With user-level security a client must first &quot;log-on&quot; with a 
    valid username and password (which can be mapped using the <smbconfoption name="username map"/> 
    parameter). Encrypted passwords (see the <smbconfoption name="encrypted passwords"/> parameter) can also
    be used in this security mode. Parameters such as <smbconfoption name="user"/> and <smbconfoption
	name="guest only"/> if set	are then applied and 
    may change the UNIX user to use on this connection, but only after 
    the user has been successfully authenticated.</para>

    <para><emphasis>Note</emphasis> that the name of the resource being 
    requested is <emphasis>not</emphasis> sent to the server until after 
    the server has successfully authenticated the client. This is why 
    guest shares don't work in user level security without allowing 
    the server to automatically map unknown users into the <smbconfoption name="guest account"/>. 
    See the <smbconfoption name="map to guest"/> parameter for details on doing this.</para>

    <para>See also the section <link linkend="VALIDATIONSECT">NOTE ABOUT USERNAME/PASSWORD VALIDATION</link>.</para>

    <para><anchor id="SECURITYEQUALSDOMAIN"/><emphasis>SECURITY = DOMAIN</emphasis></para>

    <para>This mode will only work correctly if <citerefentry><refentrytitle>net</refentrytitle>
    <manvolnum>8</manvolnum></citerefentry> has been used to add this
    machine into a Windows NT Domain. It expects the <smbconfoption name="encrypted passwords"/>
	parameter to be set to <constant>yes</constant>. In this 
    mode Samba will try to validate the username/password by passing
    it to a Windows NT Primary or Backup Domain Controller, in exactly 
    the same way that a Windows NT Server would do.</para>

    <para><emphasis>Note</emphasis> that a valid UNIX user must still 
    exist as well as the account on the Domain Controller to allow 
    Samba to have a valid UNIX account to map file access to.</para>

    <para><emphasis>Note</emphasis> that from the client's point 
    of view <command moreinfo="none">security = domain</command> is the same 
    as <command moreinfo="none">security = user</command>. It only 
    affects how the server deals with the authentication, 
    it does not in any way affect what the client sees.</para>

    <para><emphasis>Note</emphasis> that the name of the resource being 
    requested is <emphasis>not</emphasis> sent to the server until after 
    the server has successfully authenticated the client. This is why 
    guest shares don't work in user level security without allowing 
    the server to automatically map unknown users into the <smbconfoption name="guest account"/>. 
    See the <smbconfoption name="map to guest"/> parameter for details on doing this.</para>

    <para>See also the section <link linkend="VALIDATIONSECT">
    NOTE ABOUT USERNAME/PASSWORD VALIDATION</link>.</para>

    <para>See also the <smbconfoption name="password server"/> parameter and
	 the <smbconfoption name="encrypted passwords"/> parameter.</para>

    <para><anchor id="SECURITYEQUALSSHARE"/><emphasis>SECURITY = SHARE</emphasis></para> 

    <note><para>This option is deprecated as it is incompatible with SMB2</para></note>
		
    <para>When clients connect to a share level security server, they 
    need not log onto the server with a valid username and password before 
    attempting to connect to a shared resource (although modern clients 
    such as Windows 95/98 and Windows NT will send a logon request with 
    a username but no password when talking to a <command moreinfo="none">security = share
    </command> server). Instead, the clients send authentication information 
    (passwords) on a per-share basis, at the time they attempt to connect 
    to that share.</para>

    <para>Note that <command moreinfo="none">smbd</command> <emphasis>ALWAYS</emphasis> 
    uses a valid UNIX user to act on behalf of the client, even in
    <command moreinfo="none">security = share</command> level security.</para>

    <para>As clients are not required to send a username to the server
    in share level security, <command moreinfo="none">smbd</command> uses several
    techniques to determine the correct UNIX user to use on behalf
    of the client.</para>

    <para>A list of possible UNIX usernames to match with the given
    client password is constructed using the following methods :</para>

    <itemizedlist>
	<listitem>
	    <para>If the <smbconfoption name="guest only"/> parameter is set, then all the other 
	    stages are missed and only the <smbconfoption name="guest account"/> username is checked.
	    </para>
	</listitem>

	<listitem>
	    <para>Is a username is sent with the share connection 
	    request, then this username (after mapping - see <smbconfoption name="username map"/>), 
	    is added as a potential username.
	    </para>
	</listitem>

	<listitem>
	    <para>If the client did a previous <emphasis>logon
	    </emphasis> request (the SessionSetup SMB call) then the 
	    username sent in this SMB will be added as a potential username.
	    </para>
	</listitem>

	<listitem>
	    <para>The name of the service the client requested is 
	    added as a potential username.
	    </para>
	</listitem>

	<listitem>
	    <para>The NetBIOS name of the client is added to 
	    the list as a potential username.
	    </para>
	</listitem>

	<listitem>
	    <para>Any users on the <smbconfoption name="user"/> list are added as potential usernames.
	    </para>
	</listitem>
    </itemizedlist>

    <para>If the <parameter moreinfo="none">guest only</parameter> parameter is 
    not set, then this list is then tried with the supplied password. 
    The first user for whom the password matches will be used as the 
    UNIX user.</para>

    <para>If the <parameter moreinfo="none">guest only</parameter> parameter is 
    set, or no username can be determined then if the share is marked 
    as available to the <parameter moreinfo="none">guest account</parameter>, then this 
    guest user will be used, otherwise access is denied.</para>

    <para>Note that it can be <emphasis>very</emphasis> confusing 
    in share-level security as to which UNIX username will eventually
    be used in granting access.</para>

    <para>See also the section <link linkend="VALIDATIONSECT">
    NOTE ABOUT USERNAME/PASSWORD VALIDATION</link>.</para>

    <para><anchor id="SECURITYEQUALSSERVER"/><emphasis>SECURITY = SERVER</emphasis></para>

    <para>
	In this depicted mode Samba will try to validate the username/password by passing it to another SMB server, such as an
	NT box. If this fails it will revert to <command moreinfo="none">security = user</command>. It expects the
	<smbconfoption name="encrypted passwords"/> parameter to be set to <constant>yes</constant>, unless the remote
	server does not support them.  However note that if encrypted passwords have been negotiated then Samba cannot
	revert back to checking the UNIX password file, it must have a valid <filename
	moreinfo="none">smbpasswd</filename> file to check users against. See the chapter about the User Database in
	the Samba HOWTO Collection for details on how to set this up.
</para>

	<note><para>This mode of operation has
    significant pitfalls since it is more vulnerable to
    man-in-the-middle attacks and server impersonation.  In particular,
    this mode of operation can cause significant resource consumption on
    the PDC, as it must maintain an active connection for the duration
    of the user's session.  Furthermore, if this connection is lost,
    there is no way to reestablish it, and further authentications to the
    Samba server may fail (from a single client, till it disconnects).
	</para></note>

	<note><para>If the client selects NTLMv2 authentication, then this mode of operation <emphasis>will fail</emphasis>
	</para></note>

	<note><para>From the client's point of 
    view, <command moreinfo="none">security = server</command> is the
    same as <command moreinfo="none">security = user</command>.  It
    only affects how the server deals  with the authentication, it does
	not in any way affect what the  client sees.</para></note>

    <note><para>This option is deprecated, and may be removed in future</para></note>

    <para><emphasis>Note</emphasis> that the name of the resource being 
    requested is <emphasis>not</emphasis> sent to the server until after 
    the server has successfully authenticated the client. This is why 
    guest shares don't work in user level security without allowing 
    the server to automatically map unknown users into the <smbconfoption name="guest account"/>. 
    See the <smbconfoption name="map to guest"/> parameter for details on doing this.</para>

    <para>See also the section <link linkend="VALIDATIONSECT">
    NOTE ABOUT USERNAME/PASSWORD VALIDATION</link>.</para>

    <para>See also the <smbconfoption name="password server"/> parameter and the 
	<smbconfoption name="encrypted passwords"/> parameter.</para>

	<para><anchor id="SECURITYEQUALSADS"/><emphasis>SECURITY = ADS</emphasis></para>
	
	<para>In this mode, Samba will act as a domain member in an ADS realm. To operate 
		in this mode, the machine running Samba will need to have Kerberos installed 
		and configured and Samba will need to be joined to the ADS realm using the 
		net utility. </para>
	
	<para>Note that this mode does NOT make Samba operate as a Active Directory Domain 
		Controller. </para>
	
	<para>Read the chapter about Domain Membership in the HOWTO for details.</para>
</description>

<related>realm</related>
<related>encrypt passwords</related>

<value type="default">USER</value>
<value type="example">DOMAIN</value>
</samba:parameter>