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