summaryrefslogtreecommitdiff
path: root/docs/Samba-HOWTO-Collection/TOSHARG-Install.xml
blob: 1cec899cdde93c9528996152ae3b99e4965c0d11 (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
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
<chapter id="install">
<chapterinfo>
	&author.tridge;
	&author.jelmer;
	&author.jht;
	&author.kauer;
	&author.danshearer;
	<!-- Isn't some of this written by others as well? -->

</chapterinfo>

<title>How to Install and Test SAMBA</title>

<sect1>
	<title>Obtaining and Installing Samba</title>

	<para>
	Binary packages of Samba are included in almost any Linux or
	UNIX distribution. There are also some packages available at 
	<ulink url="http://samba.org/">the Samba home-page</ulink>. Refer to 
	the manual of your operating system for details on installing packages 
	for your specific operating system.
	</para>

	<para>If you need to compile Samba from source, check 
	<link linkend="compiling">How to compile Samba.</link>
	</para>

</sect1>

<sect1>
	<title>Configuring Samba (smb.conf)</title>

	<para>
	Samba's configuration is stored in the &smb.conf; file, which
	usually resides in <filename>/etc/samba/smb.conf</filename> 
	or <filename>/usr/local/samba/lib/smb.conf</filename>. You can either 
	edit this file yourself or do it using one of the many graphical 
	tools that are available, such as the Web-based interface SWAT, that 
	is included with Samba.
	</para>

	<sect2>
	<title>Configuration file syntax</title>

	<para>The &smb.conf; file uses the same syntax as the various old 
	.ini files in Windows 3.1: Each file consists of various sections, 
	which are started by putting the section name between brackets ([]) 
	on a new line. Each contains zero or more key/value-pairs separated by an 
	equality sign (=). The file is just a plain-text file, so you can 
	open and edit it with your favorite editing tool.</para>

	<para>Each section in the &smb.conf; file represents a share 
	on the Samba server. The section <quote>global</quote> is special, since it 
	contains settings that apply to the whole Samba server and not 
	to one share in particular.</para>

<para><link linkend="smbconfminimal">Following example</link> contains a very minimal &smb.conf;.
	<indexterm><primary>minimal configuration</primary></indexterm>
</para>

	<smbconfexample id="smbconfminimal">
		<title>A minimal smb.conf</title>

		<smbconfsection name="[global]"/>
		<smbconfoption name="workgroup">WKG</smbconfoption>
		<smbconfoption name="netbios name">MYNAME</smbconfoption>
		<smbconfsection name="[share1]"/>
		<smbconfoption name="path">/tmp</smbconfoption>

		<smbconfsection name="[share2]"/>
		<smbconfoption name="path">/my_shared_folder</smbconfoption>
		<smbconfoption name="comment">Some random files</smbconfoption>
	</smbconfexample>

</sect2>

<sect2>
	<title>Starting Samba</title>

	<para>
	Samba essentially consists of two or three daemons. A daemon is a UNIX application that runs in the background and provides services.
	An example of a service is the Apache Web server for which the daemon is called <command>httpd</command>. In the case of Samba there
	are three daemons, two of which are needed as a minimum.
	</para>

	<para>
	The Samba server is made up of the following daemons:
	</para>

	<variablelist>
		<varlistentry><term>nmbd</term>
			<listitem><para>
			<indexterm><primary>smbd</primary></indexterm>
			<indexterm><primary>starting samba</primary><secondary>smbd</secondary></indexterm>
			This daemon handles all name registration and resolution requests. It is the primary vehicle involved
			in network browsing. It handles all UDP based protocols. The <command>nmbd</command> daemon should
			be the first command started as part of the Samba start-up process.
			</para></listitem>
		</varlistentry>

		<varlistentry><term>smbd</term>
			<listitem><para>
			<indexterm><primary>nmbd</primary></indexterm>
			<indexterm><primary>starting samba</primary><secondary>nmbd</secondary></indexterm>
			This daemon handles all TCP/IP based connection services for file and print based operations. It also
			manages local authentication. It should be started immediately following the start-up of <command>nmbd</command>.
			</para></listitem>
		</varlistentry>

		<varlistentry><term>winbindd</term>
			<listitem><para>
			<indexterm><primary>winbindd</primary></indexterm>
			<indexterm><primary>starting samba</primary><secondary>winbindd</secondary></indexterm>
			This daemon should be started when Samba is a member of a Windows NT4 or ADS Domain. It is also needed when
			Samba has trust relationships with another Domain. The <command>winbindd</command> daemon will check the
			&smb.conf; file for the presence of the <parameter>idmap uid</parameter> and <parameter>idmap gid</parameter>
			parameters. If they are not found <command>winbindd</command> will bail-out and refuse to start.
			</para></listitem>
		</varlistentry>
	</variablelist>

	<para>
	When Samba has been packaged by an operating system vendor the start-up process is typically a custom feature of its
	integration into the platform as a whole. Please refer to your operating system platform administration manuals for
	specific information pertaining to correct management of Samba start-up.
	</para>

</sect2>
	
<sect2>
	<title>Example Configuration</title>
	
	<para>
	There are sample configuration files in the examples subdirectory in the
	distribution. It is suggested you read them carefully so you can see how the options
	go together in practice. See the man page for all the options. 
	It might be worthwhile to start out with the smb.conf.default 
	configuration file and adapt it to your needs. It contains plenty of 
	comments.
	</para>

	<para>
	The simplest useful configuration file would contain something like shown in
	<link linkend="simple-example">the next example</link>.
	</para>

	<para>
	<indexterm><primary>simple configuration</primary></indexterm>
	<smbconfexample id="simple-example">
		<title>Another simple smb.conf File</title>
<smbconfsection name="[global]"/>
<smbconfoption name="workgroup">&example.workgroup;</smbconfoption>

<smbconfsection name="[homes]"/>
<smbconfoption name="guest ok">no</smbconfoption>
<smbconfoption name="read only">no</smbconfoption>
	</smbconfexample>
	</para>
	
	<para>
	This will allow connections by anyone with an account on the server, using either
	their login name or <smbconfsection name="homes"/> as the service name.
	(Note: The workgroup that Samba should appear in must also be set. The default
	workgroup name is WORKGROUP.)
	</para>
	
	<para>
	Make sure you put the &smb.conf; file in the correct place.
	</para>

	<para>
	For more information about security settings for the 
	<smbconfsection name="[homes]"/> share please refer to 
	<link linkend="securing-samba">Securing Samba</link> chapter.
	</para>

<sect3>
	<title>Test Your Config File with <command>testparm</command></title>

	<para>
	It's important to validate the contents of the &smb.conf; file using the &testparm; program.
	If testparm runs correctly, it will list the loaded services. If not, it will give an error message.
	Make sure it runs correctly and that the services look reasonable before proceeding. Enter the command: 
	</para>

	<screen>
	&rootprompt; testparm /etc/samba/smb.conf
	</screen>

	<para>Testparm will parse your configuration file and report 
	any unknown parameters or incorrect syntax. </para>

	

	<para>
	Always run testparm again whenever the &smb.conf; file is changed!
	</para>

</sect3>
</sect2>

<sect2>
	<title>SWAT</title>

	<para>
	<indexterm><primary>swat</primary></indexterm>
	SWAT is a Web-based interface that can be used to facilitate the configuration of Samba. 
	SWAT might not be available in the Samba package that shipped with your platform, 
	but in a separate package. Please read the SWAT man page 
	on compiling, installing and configuring SWAT from source.
	</para>

	<para>
	To launch SWAT, just run your favorite Web browser and point it to
	<ulink url="http://localhost:901/" noescape="1">http://localhost:901/</ulink>.
	Replace <replaceable>localhost</replaceable> with the name of the computer on which
	Samba is running if that is a different computer than your browser.
	</para>

	<para>
	SWAT can be used from a browser on any IP-connected machine, but be aware that connecting from a remote
	machine leaves your connection open to password sniffing as passwords will be sent over the wire in the clear. 
	</para>

	<para>More information about SWAT can be found in <link linkend="SWAT">corresponding chapter</link>.</para>

</sect2>

</sect1>

<sect1>
	<title>List Shares Available on the Server</title>

	<para>
	To list shares that are available from the configured Samba server execute the
	following command:
	</para>

<para><screen>
&prompt;<userinput>smbclient -L <replaceable>yourhostname</replaceable></userinput>
</screen></para>

	<para>You should see a list of shares available on your server. If you do not, then
	something is incorrectly configured. This method can also be used to see what shares 
	are available on other SMB servers, such as Windows 2000.</para>

	<para>If you choose user-level security you may find that Samba requests a password
	before it will list the shares. See the <command>smbclient</command> man page for details.
	You can force it to list the shares without a password by adding the option
	<option>-N</option> to the command line. </para>
</sect1>

<sect1>
	<title>Connect with a UNIX Client</title>
	
	<para>
	Enter the following command:
<screen>
&prompt;<userinput>smbclient <replaceable> //yourhostname/aservice</replaceable></userinput>
</screen></para>
	
	<para>Typically <replaceable>yourhostname</replaceable> is the name of the host on which &smbd;
	has been installed. The <replaceable>aservice</replaceable> is any service that has been defined in the &smb.conf;
	file. Try your user name if you just have a <smbconfsection name="[homes]"/> section in the &smb.conf; file.</para>

	<para>Example: If the UNIX host is called <replaceable>bambi</replaceable> and a valid login name
	is <replaceable>fred</replaceable>, you would type:</para>

<para><screen>
&prompt;<userinput>smbclient //<replaceable>bambi</replaceable>/<replaceable>fred</replaceable></userinput>
</screen></para>
</sect1>

<sect1>
	<title>Connect from a Remote SMB Client</title>

	<para>Now that Samba is working correctly locally, you can try to 
	access it from other clients. Within a few minutes, the Samba host 
	should be listed in the Network Neighborhood on all Windows 
	clients of its subnet. Try browsing the server from another client
	or 'mounting' it.</para>

	<para>Mounting disks from a DOS, Windows or OS/2 client can be done by running a command such as:</para>

	<para><screen>
&dosprompt;<userinput>net use d: \\servername\service</userinput>
</screen></para>

	<para>Try printing, e.g.</para>

	<para>
<screen>
&dosprompt;<userinput>net use lpt1:	\\servername\spoolservice</userinput>
</screen></para>

<para>
<screen>&dosprompt;<userinput>print filename</userinput>
</screen></para>
</sect1>

<sect1>
	<title>What If Things Don't Work?</title>
	
	<para>You might want to read <link linkend="diagnosis">The Samba Checklist</link>.
	If you are still stuck, refer to <link linkend="problems">Analyzing and Solving Samba Problems</link> chapter.
	Samba has been successfully installed at thousands of sites worldwide.
	It is unlikely that your particular problem is unique, so it might be
	productive to perform an Internet search to see if someone else has encountered
	your problem and has found a way to overcome it.</para>

</sect1>

<sect1>
<title>Common Errors</title>

<para>
The following questions and issues are raised repeatedly on the Samba mailing list.
</para>

<sect2>
	<title>Large Number of smbd Processes</title>

<para>
Samba consists of three core programs: &nmbd;, &smbd;, and &winbindd;. &nmbd; is the name server message daemon,
&smbd; is the server message daemon, and &winbindd; is the daemon that handles communication with Domain Controllers.
</para>

<para>
If Samba is <emphasis>not</emphasis> running as a WINS server, then there will be one single instance of
 &nmbd; running on your system. If it is running as a WINS server then there will be
two instances &smbmdash; one to handle the WINS requests.
</para>

<para>
&smbd; handles all connection requests. It spawns a new process for each client
connection made. That is why you may see so many of them, one per client connection.
</para>

<para>
&winbindd; will run as one or two daemons, depending on whether or not it is being
run in <emphasis>split mode</emphasis> (in which case there will be two instances).
</para>

</sect2>

	<sect2>
		<title>Error Message: open_oplock_ipc</title>

	<para>An error message is observed in the log files when &smbd; is started: <quote>open_oplock_ipc: Failed to get local UDP socket
	for address 100007f. Error was Cannot assign requested.</quote></para>

	<para>Your loopback device isn't working correctly. Make sure it is configured correctly. The loopback
	device is an internal (virtual) network device with the IP address <emphasis>127.0.0.1</emphasis>.
	Read your OS documentation for details on how to configure the loopback on your system.</para>

	</sect2>

	<sect2>
		<title><quote><errorname>The network name cannot be found</errorname></quote></title>

		<para>
		This error can be caused by one of these mis-configurations:
		</para>

		<itemizedlist>
			<listitem><para>You specified an non-existing path
			for the share in &smb.conf;.</para></listitem>

			<listitem><para>The user you are trying to access the share with does not 
			have sufficient permissions to access the path for
			the share. Both read (r) and access (x) should be possible.</para></listitem>

			<listitem><para>The share you are trying to access does not exist.</para></listitem>
	</itemizedlist>

	</sect2>
</sect1>

</chapter>