150f071b7804543b668e95c6ebb9721a189084b4
[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 "host not found" 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 <para>
147 Note: Modern Linux distributions install ipchains/iptables by default. 
148 This is a common problem that is often overlooked.
149 </para>
150 </step>
151
152 <step performance="required">
153 <para>
154 Run the command <userinput>smbclient -L BIGSERVER</userinput> on the unix box. You
155 should get a list of available shares back. 
156 </para>
157
158 <para>
159 If you get a error message containing the string "Bad password" then
160 you probably have either an incorrect <command>hosts allow</command>, 
161 <command>hosts deny</command> or <command>valid users</command> line in your 
162 &smb.conf;, or your guest account is not
163 valid. Check what your guest account is using &testparm; and
164 temporarily remove any <command>hosts allow</command>, <command>hosts deny</command>, <command>valid users</command> or <command>invalid users</command> lines.
165 </para>
166
167 <para>
168 If you get a "connection refused" response then the smbd server may
169 not be running. If you installed it in inetd.conf then you probably edited
170 that file incorrectly. If you installed it as a daemon then check that
171 it is running, and check that the netbios-ssn port is in a LISTEN
172 state using <userinput>netstat -a</userinput>.
173 </para>
174
175 <note><para>
176 Some Unix / Linux systems use <command>xinetd</command> in place of
177 <command>inetd</command>. Check your system documentation for the location
178 of the control file/s for your particular system implementation of
179 this network super daemon.
180 </para></note>
181
182 <para>
183 If you get a "session request failed" then the server refused the
184 connection. If it says "Your server software is being unfriendly" then
185 its probably because you have invalid command line parameters to &smbd;,
186 or a similar fatal problem with the initial startup of &smbd;. Also
187 check your config file (&smb.conf;) for syntax errors with &testparm;
188 and that the various directories where samba keeps its log and lock
189 files exist.
190 </para>
191
192 <para>
193 There are a number of reasons for which smbd may refuse or decline
194 a session request. The most common of these involve one or more of
195 the following &smb.conf; file entries:
196 </para>
197
198 <para><programlisting>
199         hosts deny = ALL
200         hosts allow = xxx.xxx.xxx.xxx/yy
201         bind interfaces only = Yes
202 </programlisting></para>
203
204 <para>
205 In the above, no allowance has been made for any session requests that
206 will automatically translate to the loopback adaptor address 127.0.0.1.
207 To solve this problem change these lines to:
208 </para>
209
210 <para><programlisting>
211         hosts deny = ALL
212         hosts allow = xxx.xxx.xxx.xxx/yy 127.
213 </programlisting></para>
214
215 <para>
216 Do NOT use the <command>bind interfaces only</command> parameter where you 
217 may wish to
218 use the samba password change facility, or where &smbclient; may need to
219 access a local service for name resolution or for local resource
220 connections. (Note: the <command>bind interfaces only</command> parameter deficiency
221 where it will not allow connections to the loopback address will be
222 fixed soon).
223 </para>
224
225 <para>
226 Another common cause of these two errors is having something already running 
227 on port 139, such as Samba (ie: smbd is running from <application>inetd</application> already) or
228 something like Digital's Pathworks. Check your <filename>inetd.conf</filename> file before trying
229 to start &smbd; as a daemon, it can avoid a lot of frustration!
230 </para>
231
232 <para>
233 And yet another possible cause for failure of this test is when the subnet mask
234 and / or broadcast address settings are incorrect. Please check that the
235 network interface IP Address / Broadcast Address / Subnet Mask settings are
236 correct and that Samba has correctly noted these in the <filename>log.nmb</filename> file.
237 </para>
238
239 </step>
240
241 <step performance="required">
242
243 <para>
244 Run the command <userinput>nmblookup -B BIGSERVER __SAMBA__</userinput>. You should get the
245 IP address of your Samba server back.
246 </para>
247
248 <para>
249 If you don't then nmbd is incorrectly installed. Check your <filename>inetd.conf</filename>
250 if you run it from there, or that the daemon is running and listening
251 to udp port 137.
252 </para>
253
254 <para>
255 One common problem is that many inetd implementations can't take many
256 parameters on the command line. If this is the case then create a
257 one-line script that contains the right parameters and run that from
258 inetd.
259 </para>
260
261 </step>
262
263 <step performance="required">
264
265 <para>run the command <userinput>nmblookup -B ACLIENT '*'</userinput></para>
266
267 <para>
268 You should get the PCs IP address back. If you don't then the client
269 software on the PC isn't installed correctly, or isn't started, or you
270 got the name of the PC wrong. 
271 </para>
272
273 <para>
274 If ACLIENT doesn't resolve via DNS then use the IP address of the
275 client in the above test.
276 </para>
277
278 </step>
279
280 <step performance="required">
281
282 <para>
283 Run the command <userinput>nmblookup -d 2 '*'</userinput>
284 </para>
285
286 <para>
287 This time we are trying the same as the previous test but are trying
288 it via a broadcast to the default broadcast address. A number of
289 Netbios/TCPIP hosts on the network should respond, although Samba may
290 not catch all of the responses in the short time it listens. You
291 should see "got a positive name query response" messages from several
292 hosts.
293 </para>
294
295 <para>
296 If this doesn't give a similar result to the previous test then
297 nmblookup isn't correctly getting your broadcast address through its
298 automatic mechanism. In this case you should experiment with the
299 <command>interfaces</command> option in &smb.conf; to manually configure your IP
300 address, broadcast and netmask. 
301 </para>
302
303 <para>
304 If your PC and server aren't on the same subnet then you will need to
305 use the <parameter>-B</parameter> option to set the broadcast address to that of the PCs
306 subnet.
307 </para>
308
309 <para>
310 This test will probably fail if your subnet mask and broadcast address are
311 not correct. (Refer to TEST 3 notes above).
312 </para>
313
314 </step>
315
316 <step performance="required">
317
318 <para>
319 Run the command <userinput>smbclient //BIGSERVER/TMP</userinput>. You should 
320 then be prompted for a password. You should use the password of the account
321 you are logged into the unix box with. If you want to test with
322 another account then add the <parameter>-U <replaceable>accountname</replaceable></parameter> option to the end of
323 the command line.  eg: 
324 <userinput>smbclient //bigserver/tmp -Ujohndoe</userinput>
325 </para>
326
327 <note><para>
328 It is possible to specify the password along with the username
329 as follows:
330 <userinput>smbclient //bigserver/tmp -Ujohndoe%secret</userinput>
331 </para></note>
332
333 <para>
334 Once you enter the password you should get the <prompt>smb></prompt> prompt. If you
335 don't then look at the error message. If it says "invalid network
336 name" then the service "tmp" is not correctly setup in your &smb.conf;.
337 </para>
338
339 <para>
340 If it says "bad password" then the likely causes are:
341 </para>
342
343 <orderedlist>
344 <listitem>
345         <para>
346         you have shadow passords (or some other password system) but didn't
347         compile in support for them in &smbd;
348         </para>
349 </listitem>
350
351 <listitem>
352         <para>
353         your <command>valid users</command> configuration is incorrect
354         </para>
355 </listitem>
356
357 <listitem>
358         <para>
359         you have a mixed case password and you haven't enabled the <command>password
360         level</command> option at a high enough level
361         </para>
362 </listitem>
363
364 <listitem>
365         <para>
366         the <command>path =</command> line in &smb.conf; is incorrect. Check it with &testparm;
367         </para>
368 </listitem>
369
370 <listitem>
371         <para>
372         you enabled password encryption but didn't create the SMB encrypted
373         password file
374         </para>
375 </listitem>
376 </orderedlist>
377
378 <para>
379 Once connected you should be able to use the commands 
380 <command>dir</command> <command>get</command> <command>put</command> etc. 
381 Type <command>help <replaceable>command</replaceable></command> for instructions. You should
382 especially check that the amount of free disk space shown is correct
383 when you type <command>dir</command>.
384 </para>
385
386 </step>
387
388 <step performance="required">
389
390 <para>
391 On the PC, type the command <userinput>net view \\BIGSERVER</userinput>. You will 
392 need to do this from within a "dos prompt" window. You should get back a 
393 list of available shares on the server.
394 </para>
395
396 <para>
397 If you get a "network name not found" or similar error then netbios
398 name resolution is not working. This is usually caused by a problem in
399 nmbd. To overcome it you could do one of the following (you only need
400 to choose one of them):
401 </para>
402
403 <orderedlist>
404 <listitem><para>
405         fixup the &nmbd; installation
406 </para></listitem>
407
408 <listitem><para>
409         add the IP address of BIGSERVER to the <command>wins server</command> box in the
410         advanced tcp/ip setup on the PC.
411 </para></listitem>
412
413 <listitem><para>
414         enable windows name resolution via DNS in the advanced section of
415         the tcp/ip setup
416 </para></listitem>
417
418 <listitem><para>
419         add BIGSERVER to your lmhosts file on the PC.
420 </para></listitem>
421 </orderedlist>
422
423 <para>
424 If you get a "invalid network name" or "bad password error" then the
425 same fixes apply as they did for the <userinput>smbclient -L</userinput> test above. In
426 particular, make sure your <command>hosts allow</command> line is correct (see the man
427 pages)
428 </para>
429
430 <para>
431 Also, do not overlook that fact that when the workstation requests the
432 connection to the samba server it will attempt to connect using the 
433 name with which you logged onto your Windows machine. You need to make
434 sure that an account exists on your Samba server with that exact same
435 name and password.
436 </para>
437
438 <para>
439 If you get "specified computer is not receiving requests" or similar
440 it probably means that the host is not contactable via tcp services.
441 Check to see if the host is running tcp wrappers, and if so add an entry in
442 the <filename>hosts.allow</filename> file for your client (or subnet, etc.)
443 </para>
444
445 </step>
446
447 <step performance="required">
448
449 <para>
450 Run the command <userinput>net use x: \\BIGSERVER\TMP</userinput>. You should 
451 be prompted for a password then you should get a "command completed 
452 successfully" message. If not then your PC software is incorrectly 
453 installed or your smb.conf is incorrect. make sure your <command>hosts allow</command>
454 and other config lines in &smb.conf; are correct.
455 </para>
456
457 <para>
458 It's also possible that the server can't work out what user name to
459 connect you as. To see if this is the problem add the line <command>user =
460 <replaceable>username</replaceable></command> to the <command>[tmp]</command> section of 
461 &smb.conf; where <replaceable>username</replaceable> is the
462 username corresponding to the password you typed. If you find this
463 fixes things you may need the username mapping option. 
464 </para>
465
466 <para>
467 It might also be the case that your client only sends encrypted passwords 
468 and you have <command>encrypt passwords = no</command> in &smb.conf;
469 Turn it back on to fix.
470 </para>
471
472 </step>
473
474 <step performance="required">
475
476 <para>
477 Run the command <userinput>nmblookup -M <replaceable>testgroup</replaceable></userinput> where 
478 <replaceable>testgroup</replaceable> is the name of the workgroup that your Samba server and 
479 Windows PCs belong to. You should get back the IP address of the 
480 master browser for that workgroup.
481 </para>
482
483 <para>
484 If you don't then the election process has failed. Wait a minute to
485 see if it is just being slow then try again. If it still fails after
486 that then look at the browsing options you have set in &smb.conf;. Make
487 sure you have <command>preferred master = yes</command> to ensure that 
488 an election is held at startup.
489 </para>
490
491 </step>
492
493 <step performance="required">
494
495 <para>
496 >From file manager try to browse the server. Your samba server should
497 appear in the browse list of your local workgroup (or the one you
498 specified in smb.conf). You should be able to double click on the name
499 of the server and get a list of shares. If you get a "invalid
500 password" error when you do then you are probably running WinNT and it
501 is refusing to browse a server that has no encrypted password
502 capability and is in user level security mode. In this case either set
503 <command>security = server</command> AND 
504 <command>password server = Windows_NT_Machine</command> in your
505 &smb.conf; file, or make sure <command>encrypted passwords</command> is
506 set to "yes".
507 </para>
508
509 </step>
510 </procedure>
511 </sect1>
512
513 <sect1>
514 <title>Still having troubles?</title>
515
516 <para>Read the chapter on 
517 <link linkend="problems">Analysing and Solving Problems</link>.
518 </para>
519
520 </sect1>
521
522 </chapter>