Very large number of markup fixes, layout updates, etc.
[samba.git] / docs / docbook / projdoc / Diagnosis.xml
1 <chapter id="diagnosis">
2 <chapterinfo>
3         &author.tridge;
4         &author.jelmer;
5         <pubdate>Wed Jan 15</pubdate>
6 </chapterinfo>
7
8 <title>The samba checklist</title>
9
10 <sect1>
11 <title>Introduction</title>
12
13 <para>
14 This file contains a list of tests you can perform to validate your
15 Samba server. It also tells you what the likely cause of the problem
16 is if it fails any one of these steps. If it passes all these tests
17 then it is probably working fine.
18 </para>
19
20 <para>
21 You should do ALL the tests, in the order shown. We have tried to
22 carefully choose them so later tests only use capabilities verified in
23 the earlier tests.  However, do not stop at the first error as there
24 have been some instances when continuing with the tests has helped
25 to solve a problem.
26 </para>
27
28 <para>
29 If you send one of the samba mailing lists  an email saying "it doesn't work"
30 and you have not followed this test procedure then you should not be surprised
31 if your email is ignored.
32 </para>
33
34 </sect1>
35
36 <sect1>
37 <title>Assumptions</title>
38
39 <para>
40 In all of the tests it is assumed you have a Samba server called 
41 BIGSERVER and a PC called ACLIENT both in workgroup TESTGROUP.
42 </para>
43
44 <para>
45 The procedure is similar for other types of clients.
46 </para>
47
48 <para>
49 It is also assumed you know the name of an available share in your
50 &smb.conf;. I will assume this share is called <replaceable>tmp</replaceable>.
51 You can add a <replaceable>tmp</replaceable> share like this by adding the
52 following to &smb.conf;:
53 </para>
54
55 <para><programlisting>
56
57 [tmp]
58  comment = temporary files 
59  path = /tmp
60  read only = yes
61
62 </programlisting>
63 </para>
64
65 <note><para>
66 These tests assume version 3.0 or later of the samba suite.
67 Some commands shown did not exist in earlier versions. 
68 </para></note>
69
70 <para>
71 Please pay attention to the error messages you receive. If any error message
72 reports that your server is being unfriendly you should first check that your
73 IP name resolution is correctly set up. eg: Make sure your <filename>/etc/resolv.conf</filename>
74 file points to name servers that really do exist.
75 </para>
76
77 <para>
78 Also, if you do not have DNS server access for name resolution please check
79 that the settings for your &smb.conf; file results in <command>dns proxy = no</command>. The
80 best way to check this is with <userinput>testparm smb.conf</userinput>.
81 </para>
82
83 <para>
84 It is helpful to monitor the log files during testing by using the
85 <command>tail -F <replaceable>log_file_name</replaceable></command> in a separate
86 terminal console (use ctrl-alt-F1 through F6 or multiple terminals in X). 
87 Relevant log files can be found (for default installations) in
88 <filename>/usr/local/samba/var</filename>.  Also, connection logs from
89 machines can be found here or possibly in <filename>/var/log/samba</filename>
90 depending on how or if you specified logging in your &smb.conf; file.
91 </para>
92
93 <para>
94 If you make changes to your &smb.conf; file while going through these test,
95 don't forget to restart &smbd; and &nmbd;.
96 </para>
97
98 </sect1>
99
100 <sect1>
101 <title>The tests</title>
102 <procedure>
103 <title>Diagnosing your samba server</title>
104
105 <step performance="required">
106 <para>
107 In the directory in which you store your &smb.conf; file, run the command
108 <userinput>testparm smb.conf</userinput>. If it reports any errors then your &smb.conf;
109 configuration file is faulty.
110 </para>
111
112 <note><para>
113 Your &smb.conf; file may be located in: <filename>/etc/samba</filename>
114 Or in:   <filename>/usr/local/samba/lib</filename>
115 </para></note>
116 </step>
117
118 <step performance="required">
119 <para>
120 Run the command <userinput>ping BIGSERVER</userinput> from the PC and 
121 <userinput>ping ACLIENT</userinput> from
122 the unix box. If you don't get a valid response then your TCP/IP
123 software is not correctly installed. 
124 </para>
125
126 <para>
127 Note that you will need to start a "dos prompt" window on the PC to
128 run ping.
129 </para>
130
131 <para>
132 If you get a message saying <errorname>host not found</errorname> or similar then your DNS
133 software or <filename>/etc/hosts</filename> file is not correctly setup.
134 It is possible to
135 run samba without DNS entries for the server and client, but I assume
136 you do have correct entries for the remainder of these tests. 
137 </para>
138
139 <para>
140 Another reason why ping might fail is if your host is running firewall 
141 software. You will need to relax the rules to let in the workstation
142 in question, perhaps by allowing access from another subnet (on Linux
143 this is done via the <application>ipfwadm</application> program.)
144 </para>
145
146 <note>
147 <para>
148 Modern Linux distributions install ipchains/iptables by default. 
149 This is a common problem that is often overlooked.
150 </para>
151 </note>
152 </step>
153
154 <step performance="required">
155 <para>
156 Run the command <userinput>smbclient -L BIGSERVER</userinput> on the unix box. You
157 should get a list of available shares back. 
158 </para>
159
160 <para>
161 If you get a error message containing the string "Bad password" then
162 you probably have either an incorrect <command>hosts allow</command>, 
163 <command>hosts deny</command> or <command>valid users</command> line in your 
164 &smb.conf;, or your guest account is not
165 valid. Check what your guest account is using &testparm; and
166 temporarily remove any <command>hosts allow</command>, <command>hosts deny</command>, <command>valid users</command> or <command>invalid users</command> lines.
167 </para>
168
169 <para>
170 If you get a <errorname>connection refused</errorname> response then the smbd server may
171 not be running. If you installed it in inetd.conf then you probably edited
172 that file incorrectly. If you installed it as a daemon then check that
173 it is running, and check that the netbios-ssn port is in a LISTEN
174 state using <userinput>netstat -a</userinput>.
175 </para>
176
177 <note><para>
178 Some Unix / Linux systems use <command>xinetd</command> in place of
179 <command>inetd</command>. Check your system documentation for the location
180 of the control file/s for your particular system implementation of
181 this network super daemon.
182 </para></note>
183
184 <para>
185 If you get a <errorname>session request failed</errorname> then the server refused the
186 connection. If it says "Your server software is being unfriendly" then
187 its probably because you have invalid command line parameters to &smbd;,
188 or a similar fatal problem with the initial startup of &smbd;. Also
189 check your config file (&smb.conf;) for syntax errors with &testparm;
190 and that the various directories where samba keeps its log and lock
191 files exist.
192 </para>
193
194 <para>
195 There are a number of reasons for which smbd may refuse or decline
196 a session request. The most common of these involve one or more of
197 the following &smb.conf; file entries:
198 </para>
199
200 <para><programlisting>
201         hosts deny = ALL
202         hosts allow = xxx.xxx.xxx.xxx/yy
203         bind interfaces only = Yes
204 </programlisting></para>
205
206 <para>
207 In the above, no allowance has been made for any session requests that
208 will automatically translate to the loopback adaptor address 127.0.0.1.
209 To solve this problem change these lines to:
210 </para>
211
212 <para><programlisting>
213         hosts deny = ALL
214         hosts allow = xxx.xxx.xxx.xxx/yy 127.
215 </programlisting></para>
216
217 <para>
218 Do <strong>not</strong> use the <command>bind interfaces only</command> parameter where you 
219 may wish to
220 use the samba password change facility, or where &smbclient; may need to
221 access a local service for name resolution or for local resource
222 connections. (Note: the <command>bind interfaces only</command> parameter deficiency
223 where it will not allow connections to the loopback address will be
224 fixed soon).
225 </para>
226
227 <para>
228 Another common cause of these two errors is having something already running 
229 on port <constant>139</constant>, such as Samba 
230 (ie: &smbd; is running from <application>inetd</application> already) or
231 something like Digital's Pathworks. Check your <filename>inetd.conf</filename> file before trying
232 to start &smbd; as a daemon, it can avoid a lot of frustration!
233 </para>
234
235 <para>
236 And yet another possible cause for failure of this test is when the subnet mask
237 and / or broadcast address settings are incorrect. Please check that the
238 network interface IP Address / Broadcast Address / Subnet Mask settings are
239 correct and that Samba has correctly noted these in the <filename>log.nmb</filename> file.
240 </para>
241
242 </step>
243
244 <step performance="required">
245
246 <para>
247 Run the command <userinput>nmblookup -B BIGSERVER __SAMBA__</userinput>. You should get the
248 IP address of your Samba server back.
249 </para>
250
251 <para>
252 If you don't then nmbd is incorrectly installed. Check your <filename>inetd.conf</filename>
253 if you run it from there, or that the daemon is running and listening
254 to udp port 137.
255 </para>
256
257 <para>
258 One common problem is that many inetd implementations can't take many
259 parameters on the command line. If this is the case then create a
260 one-line script that contains the right parameters and run that from
261 inetd.
262 </para>
263
264 </step>
265
266 <step performance="required">
267
268 <para>run the command <userinput>nmblookup -B ACLIENT '*'</userinput></para>
269
270 <para>
271 You should get the PCs IP address back. If you don't then the client
272 software on the PC isn't installed correctly, or isn't started, or you
273 got the name of the PC wrong. 
274 </para>
275
276 <para>
277 If ACLIENT doesn't resolve via DNS then use the IP address of the
278 client in the above test.
279 </para>
280
281 </step>
282
283 <step performance="required">
284
285 <para>
286 Run the command <userinput>nmblookup -d 2 '*'</userinput>
287 </para>
288
289 <para>
290 This time we are trying the same as the previous test but are trying
291 it via a broadcast to the default broadcast address. A number of
292 Netbios/TCPIP hosts on the network should respond, although Samba may
293 not catch all of the responses in the short time it listens. You
294 should see <errorname>got a positive name query response</errorname>
295 messages from several hosts.
296 </para>
297
298 <para>
299 If this doesn't give a similar result to the previous test then
300 nmblookup isn't correctly getting your broadcast address through its
301 automatic mechanism. In this case you should experiment with the
302 <command>interfaces</command> option in &smb.conf; to manually configure your IP
303 address, broadcast and netmask. 
304 </para>
305
306 <para>
307 If your PC and server aren't on the same subnet then you will need to
308 use the <parameter>-B</parameter> option to set the broadcast address to that of the PCs
309 subnet.
310 </para>
311
312 <para>
313 This test will probably fail if your subnet mask and broadcast address are
314 not correct. (Refer to TEST 3 notes above).
315 </para>
316
317 </step>
318
319 <step performance="required">
320
321 <para>
322 Run the command <userinput>smbclient //BIGSERVER/TMP</userinput>. You should 
323 then be prompted for a password. You should use the password of the account
324 you are logged into the unix box with. If you want to test with
325 another account then add the <parameter>-U <replaceable>accountname</replaceable></parameter> option to the end of
326 the command line.  eg: 
327 <userinput>smbclient //bigserver/tmp -Ujohndoe</userinput>
328 </para>
329
330 <note><para>
331 It is possible to specify the password along with the username
332 as follows:
333 <userinput>smbclient //bigserver/tmp -Ujohndoe%secret</userinput>
334 </para></note>
335
336 <para>
337 Once you enter the password you should get the <prompt>smb></prompt> prompt. If you
338 don't then look at the error message. If it says <errorname>invalid network
339 name</errorname> then the service <emphasis>"tmp"</emphasis> is not correctly setup in your &smb.conf;.
340 </para>
341
342 <para>
343 If it says <errorname>bad password</errorname> then the likely causes are:
344 </para>
345
346 <orderedlist>
347 <listitem>
348         <para>
349         you have shadow passords (or some other password system) but didn't
350         compile in support for them in &smbd;
351         </para>
352 </listitem>
353
354 <listitem>
355         <para>
356         your <command>valid users</command> configuration is incorrect
357         </para>
358 </listitem>
359
360 <listitem>
361         <para>
362         you have a mixed case password and you haven't enabled the <command>password
363         level</command> option at a high enough level
364         </para>
365 </listitem>
366
367 <listitem>
368         <para>
369         the <command>path =</command> line in &smb.conf; is incorrect. Check it with &testparm;
370         </para>
371 </listitem>
372
373 <listitem>
374         <para>
375         you enabled password encryption but didn't map unix to samba users
376         </para>
377 </listitem>
378 </orderedlist>
379
380 <para>
381 Once connected you should be able to use the commands 
382 <command>dir</command> <command>get</command> <command>put</command> etc. 
383 Type <command>help <replaceable>command</replaceable></command> for instructions. You should
384 especially check that the amount of free disk space shown is correct
385 when you type <command>dir</command>.
386 </para>
387
388 </step>
389
390 <step performance="required">
391
392 <para>
393 On the PC, type the command <userinput>net view \\BIGSERVER</userinput>. You will 
394 need to do this from within a "dos prompt" window. You should get back a 
395 list of available shares on the server.
396 </para>
397
398 <para>
399 If you get a <errorname>network name not found</errorname> or similar error then netbios
400 name resolution is not working. This is usually caused by a problem in
401 nmbd. To overcome it you could do one of the following (you only need
402 to choose one of them):
403 </para>
404
405 <orderedlist>
406 <listitem><para>
407         fixup the &nmbd; installation
408 </para></listitem>
409
410 <listitem><para>
411         add the IP address of BIGSERVER to the <command>wins server</command> box in the
412         advanced tcp/ip setup on the PC.
413 </para></listitem>
414
415 <listitem><para>
416         enable windows name resolution via DNS in the advanced section of
417         the tcp/ip setup
418 </para></listitem>
419
420 <listitem><para>
421         add BIGSERVER to your lmhosts file on the PC.
422 </para></listitem>
423 </orderedlist>
424
425 <para>
426 If you get a <errorname>invalid network name</errorname> or <errorname>bad password error</errorname> then the
427 same fixes apply as they did for the <userinput>smbclient -L</userinput> test above. In
428 particular, make sure your <command>hosts allow</command> line is correct (see the man
429 pages)
430 </para>
431
432 <para>
433 Also, do not overlook that fact that when the workstation requests the
434 connection to the samba server it will attempt to connect using the 
435 name with which you logged onto your Windows machine. You need to make
436 sure that an account exists on your Samba server with that exact same
437 name and password.
438 </para>
439
440 <para>
441 If you get <errorname>specified computer is not receiving requests</errorname> or similar
442 it probably means that the host is not contactable via tcp services.
443 Check to see if the host is running tcp wrappers, and if so add an entry in
444 the <filename>hosts.allow</filename> file for your client (or subnet, etc.)
445 </para>
446
447 </step>
448
449 <step performance="required">
450
451 <para>
452 Run the command <userinput>net use x: \\BIGSERVER\TMP</userinput>. You should 
453 be prompted for a password then you should get a <computeroutput>command completed 
454 successfully</computeroutput> message. If not then your PC software is incorrectly 
455 installed or your smb.conf is incorrect. make sure your <command>hosts allow</command>
456 and other config lines in &smb.conf; are correct.
457 </para>
458
459 <para>
460 It's also possible that the server can't work out what user name to
461 connect you as. To see if this is the problem add the line <parameter>user =
462 <replaceable>username</replaceable></parameter> to the <parameter>[tmp]</parameter> section of 
463 &smb.conf; where <replaceable>username</replaceable> is the
464 username corresponding to the password you typed. If you find this
465 fixes things you may need the username mapping option. 
466 </para>
467
468 <para>
469 It might also be the case that your client only sends encrypted passwords 
470 and you have <parameter>encrypt passwords = no</parameter> in &smb.conf;
471 Turn it back on to fix.
472 </para>
473
474 </step>
475
476 <step performance="required">
477
478 <para>
479 Run the command <userinput>nmblookup -M <replaceable>testgroup</replaceable></userinput> where 
480 <replaceable>testgroup</replaceable> is the name of the workgroup that your Samba server and 
481 Windows PCs belong to. You should get back the IP address of the 
482 master browser for that workgroup.
483 </para>
484
485 <para>
486 If you don't then the election process has failed. Wait a minute to
487 see if it is just being slow then try again. If it still fails after
488 that then look at the browsing options you have set in &smb.conf;. Make
489 sure you have <parameter>preferred master = yes</parameter> to ensure that 
490 an election is held at startup.
491 </para>
492
493 </step>
494
495 <step performance="required">
496
497 <para>
498 >From file manager try to browse the server. Your samba server should
499 appear in the browse list of your local workgroup (or the one you
500 specified in smb.conf). You should be able to double click on the name
501 of the server and get a list of shares. If you get a "invalid
502 password" error when you do then you are probably running WinNT and it
503 is refusing to browse a server that has no encrypted password
504 capability and is in user level security mode. In this case either set
505 <parameter>security = server</parameter> AND 
506 <parameter>password server = Windows_NT_Machine</parameter> in your
507 &smb.conf; file, or make sure <parameter>encrypted passwords</parameter> is
508 set to "yes".
509 </para>
510
511 </step>
512 </procedure>
513 </sect1>
514
515 <sect1>
516 <title>Still having troubles?</title>
517
518 <para>Read the chapter on 
519 <link linkend="problems">Analysing and Solving Problems</link>.
520 </para>
521
522 </sect1>
523
524 </chapter>