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> 18This file contains a list of tests you can perform to validate your 19Samba server. It also tells you what the likely cause of the problem 20is if it fails any one of these steps. If it passes all these tests, 21then it is probably working fine. 22</para> 23 24<para> 25You should do all the tests in the order shown. We have tried to 26carefully choose them so later tests only use capabilities verified in 27the earlier tests. However, do not stop at the first error: there 28have been some instances when continuing with the tests has helped 29to solve a problem. 30</para> 31 32<para> 33If you send one of the Samba mailing lists an email saying, <quote>It does not work,</quote> 34and you have not followed this test procedure, you should not be surprised 35if your email is ignored. 36</para> 37 38</sect1> 39 40<sect1> 41<title>Assumptions</title> 42 43<para> 44In all of the tests, it is assumed you have a Samba server called 45BIGSERVER and a PC called ACLIENT, both in workgroup TESTGROUP. 46</para> 47 48<para> 49The procedure is similar for other types of clients. 50</para> 51 52<para> 53It 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"/>. 55You can add a <smbconfsection name="tmp"/> share like this by adding the 56lines 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> 70These tests assume version 3.0.0 or later of the Samba suite. 71Some 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> 78Please pay attention to the error messages you receive. If any error message 79reports that your server is being unfriendly, you should first check that your 80IP name resolution is correctly set up. Make sure your <filename>/etc/resolv.conf</filename> 81file 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> 89Also, if you do not have DNS server access for name resolution, please check 90that the settings for your &smb.conf; file results in <parameter>dns proxy = no</parameter>. The 91best 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> 101It is helpful to monitor the log files during testing by using the 102<command>tail -F log_file_name</command> in a separate 103terminal console (use ctrl-alt-F1 through F6 or multiple terminals in X). 104Relevant log files can be found (for default installations) in 105<filename>/usr/local/samba/var</filename>. Also, connection logs from 106machines can be found here or possibly in <filename>/var/log/samba</filename>, 107depending on how or if you specified logging in your &smb.conf; file. 108</para> 109 110<para> 111If you make changes to your &smb.conf; file while going through these test, 112remember 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> 126In 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; 128configuration file is faulty. 129</para> 130 131<note><para> 132<indexterm><primary>/etc/samba</primary></indexterm> 133<indexterm><primary>/usr/local/samba/lib</primary></indexterm> 134Your &smb.conf; file may be located in <filename>/etc/samba</filename> 135or in <filename>/usr/local/samba/lib</filename>. 136</para></note> 137</step> 138 139<step performance="required"> 140<para> 141<indexterm><primary>ping</primary></indexterm> 142Run 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, 144then your TCP/IP software is not correctly installed. 145</para> 146 147<para> 148You 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> 155If you get a message saying <quote><errorname>host not found</errorname></quote> or a similar message, then 156your DNS software or <filename>/etc/hosts</filename> file is not correctly set up. If using DNS, check that 157the <filename>/etc/resolv.conf</filename> has correct, current, entries in it. It is possible to run 158Samba without DNS entries for the server and client, but it is assumed you do have correct entries for the 159remainder 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> 166Another reason why ping might fail is if your host is running firewall 167software. You will need to relax the rules to let in the workstation 168in question, perhaps by allowing access from another subnet (on Linux 169this is done via the appropriate firewall maintenance commands <command>ipchains</command> 170or <command>iptables</command>). 171</para> 172 173<note> 174<para> 175Modern Linux distributions install ipchains/iptables by default. 176This 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> 183If 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> 189Here is a sample listing from a system that has an external Ethernet interface (eth1) on which Samba 190is not active and an internal (private network) interface (eth0) on which Samba is active: 191<screen> 192frodo:~ # iptables -L -v 193Chain 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 1971399K 1380M ACCEPT all -- eth1 any anywhere anywhere \ 198 state RELATED,ESTABLISHED 199 200Chain 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 208Chain OUTPUT (policy ACCEPT 2875K packets, 1508M bytes) 209 pkts bytes target prot opt in out source destination 210 211Chain 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> 220Run the command <command>smbclient -L BIGSERVER</command> 221on 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> 231If you get an error message containing the string <quote>bad password</quote>, then 232you 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 235temporarily 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> 241If you get a message <literal>connection refused</literal> response, then the <command>smbd</command> server may 242not be running. If you installed it in <filename>inetd.conf</filename>, then you probably edited 243that file incorrectly. If you installed it as a daemon, then check that 244it is running and check that the netbios-ssn port is in a LISTEN 245state 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> 251Some UNIX/Linux systems use <command>xinetd</command> in place of 252<command>inetd</command>. Check your system documentation for the location 253of the control files for your particular system implementation of 254the network super daemon. 255</para></note> 256 257<para> 258If you get a message saying <literal>session request failed,</literal> the server refused the 259connection. If it says <quote>Your server software is being unfriendly,</quote> then 260it's probably because you have invalid command line parameters to &smbd;, 261or a similar fatal problem with the initial startup of &smbd;. Also 262check your config file (&smb.conf;) for syntax errors with &testparm; 263and that the various directories where Samba keeps its log and lock 264files exist. 265</para> 266 267<para> 268There are a number of reasons for which smbd may refuse or decline 269a session request. The most common of these involve one or more of 270the &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> 287In <link linkend="modif1">Configuration for Allowing Connections Only from a Certain Subnet</link>, no 288allowance has been made for any session requests that will automatically translate to the loopback adapter 289address 127.0.0.1. To solve this problem, change these lines as shown in <link linkend="modif2">the following 290example</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> 306Another common cause of these two errors is having something already running on port <constant>139</constant>, 307such as Samba (&smbd; is running from <application>inetd</application> already) or Digital's Pathworks. Check 308your <filename>inetd.conf</filename> file before trying to start &smbd; as a daemon &smbmdash; it can avoid a 309lot 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> 318And yet another possible cause for failure of this test is when the subnet mask and/or broadcast address 319settings are incorrect. Please check that the network interface IP address/broadcast address/subnet mask 320settings 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> 329Run the command <command>nmblookup -B BIGSERVER __SAMBA__</command>. 330You 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> 337If you do not, then &nmbd; is incorrectly installed. Check your <filename>inetd.conf</filename> 338if you run it from there, or that the daemon is running and listening to UDP port 137. 339</para> 340 341<para> 342One common problem is that many inetd implementations can't take many 343parameters on the command line. If this is the case, then create a 344one-line script that contains the right parameters and run that from 345inetd. 346</para> 347 348</step> 349 350<step performance="required"> 351 352<para> 353<indexterm><primary>nmblookup</primary></indexterm> 354Run the command <command>nmblookup -B ACLIENT `*'</command>. 355</para> 356 357<para> 358You should get the PC's IP address back. If you do not, then the client 359software on the PC isn't installed correctly, or isn't started, or you 360got the name of the PC wrong. 361</para> 362 363<para> 364If ACLIENT does not resolve via DNS, then use the IP address of the 365client in the above test. 366</para> 367 368</step> 369 370<step performance="required"> 371 372<para> 373Run the command <command>nmblookup -d 2 `*'</command>. 374</para> 375 376<para> 377This time we are trying the same as the previous test but are trying 378it via a broadcast to the default broadcast address. A number of 379NetBIOS/TCP/IP hosts on the network should respond, although Samba may 380not catch all of the responses in the short time it listens. You 381should see the <literal>got a positive name query response</literal> 382messages from several hosts. 383</para> 384 385<para> 386<indexterm><primary>nmblookup</primary></indexterm> 387If this does not give a result similar to the previous test, then nmblookup isn't correctly getting your 388broadcast address through its automatic mechanism. In this case you should experiment with the <smbconfoption 389name="interfaces"/> option in &smb.conf; to manually configure your IP address, broadcast, and netmask. 390</para> 391 392<para> 393If 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> 398This test will probably fail if your subnet mask and broadcast address are 399not 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> 409Run the command <command>smbclient //BIGSERVER/TMP</command>. You should 410then be prompted for a password. You should use the password of the account 411with which you are logged into the UNIX box. If you want to test with 412another account, then add the <option>-U accountname</option> option to the end of 413the command line &smbmdash; for example, <command>smbclient //bigserver/tmp -Ujohndoe</command>. 414</para> 415 416<note><para> 417It 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> 422Once you enter the password, you should get the <prompt>smb></prompt> prompt. If you 423do not, then look at the error message. If it says <quote><errorname>invalid network 424name,</errorname></quote> then the service <smbconfsection name="tmp"/> is not correctly set up in your &smb.conf;. 425</para> 426 427<para> 428If it says <quote><errorname>bad password,</errorname></quote> then the likely causes are: 429</para> 430 431<orderedlist> 432<listitem> 433 <para> 434 You have shadow passwords (or some other password system) but didn't 435 compile in support for them in &smbd;. 436 </para> 437</listitem> 438 439<listitem> 440 <para> 441 Your <smbconfoption name="valid users"/> configuration is incorrect. 442 </para> 443</listitem> 444 445<listitem> 446 <para> 447 You have a mixed-case password and you haven't enabled the <smbconfoption name="password level"/> option at a high enough level. 448 </para> 449</listitem> 450 451<listitem> 452 <para> 453 The <smbconfoption name="path"/> line in &smb.conf; is incorrect. Check it with &testparm;. 454 </para> 455</listitem> 456 457<listitem> 458 <para> 459 You enabled password encryption but didn't map UNIX to Samba users. Run 460 <command>smbpasswd -a username</command> 461 </para> 462</listitem> 463</orderedlist> 464 465<para> 466<indexterm><primary>dir</primary></indexterm> 467<indexterm><primary>get</primary></indexterm> 468<indexterm><primary>put</primary></indexterm> 469<indexterm><primary>help command</primary></indexterm> 470Once connected, you should be able to use the commands <command>dir</command>, <command>get</command>, 471<command>put</command>, and so on. Type <command>help command</command> for instructions. You should 472especially check that the amount of free disk space shown is correct when you type <command>dir</command>. 473</para> 474 475</step> 476 477<step performance="required"> 478 479<para> 480<indexterm><primary>net view</primary></indexterm> 481On the PC, type the command <command>net view \\BIGSERVER</command>. You will 482need to do this from within a DOS prompt window. You should get back a 483list of shares available on the server. 484</para> 485 486<para> 487<indexterm><primary>nmbd</primary></indexterm> 488If you get a message <literal>network name not found</literal> or similar error, then NetBIOS 489name resolution is not working. This is usually caused by a problem in <command>nmbd</command>. 490To overcome it, you could do one of the following (you only need to choose one of them): 491</para> 492 493<orderedlist> 494<listitem><para> 495 Fix the &nmbd; installation. 496</para></listitem> 497 498<listitem><para> 499 Add the IP address of BIGSERVER to the <command>wins server</command> box in the 500 advanced TCP/IP setup on the PC. 501</para></listitem> 502 503<listitem><para> 504 Enable Windows name resolution via DNS in the advanced section of the TCP/IP setup. 505</para></listitem> 506 507<listitem><para> 508 Add BIGSERVER to your lmhosts file on the PC. 509</para></listitem> 510</orderedlist> 511 512<para> 513If you get a message <quote><errorname>invalid network name</errorname></quote> or 514<quote><errorname>bad password error,</errorname></quote> then apply the 515same fixes as for the <command>smbclient -L</command> test. In 516particular, make sure your <command>hosts allow</command> line is correct (see the man pages). 517</para> 518 519<para> 520Also, do not overlook that fact that when the workstation requests the 521connection to the Samba server, it will attempt to connect using the 522name with which you logged onto your Windows machine. You need to make 523sure that an account exists on your Samba server with that exact same 524name and password. 525</para> 526 527<para> 528If you get a message <quote><errorname>specified computer is not receiving requests</errorname></quote> or similar error, 529it probably means that the host is not contactable via TCP services. 530Check to see if the host is running TCP wrappers, and if so, add an entry in 531the <filename>hosts.allow</filename> file for your client (or subnet, and so on.) 532</para> 533 534</step> 535 536<step performance="required"> 537 538<para> 539Run the command <command>net use x: \\BIGSERVER\TMP</command>. You should 540be prompted for a password, then you should get a <computeroutput>command completed 541successfully</computeroutput> message. If not, then your PC software is incorrectly 542installed or your &smb.conf; is incorrect. Make sure your <parameter>hosts allow</parameter> 543and other config lines in &smb.conf; are correct. 544</para> 545 546<para> 547It's also possible that the server can't work out what username to connect you as. 548To see if this is the problem, add the line 549<smbconfoption name="user">username</smbconfoption> to the 550<smbconfsection name="[tmp]"/> section of 551&smb.conf; where <parameter>username</parameter> is the 552username corresponding to the password you typed. If you find this 553fixes things, you may need the username mapping option. 554</para> 555 556<para> 557It might also be the case that your client only sends encrypted passwords 558and you have <smbconfoption name="encrypt passwords">no</smbconfoption> in &smb.conf;. 559Change this setting to `yes' to fix this. 560</para> 561 562</step> 563 564<step performance="required"> 565 566<para> 567Run the command <command>nmblookup -M <parameter>testgroup</parameter></command> where 568<parameter>testgroup</parameter> is the name of the workgroup that your Samba server and 569Windows PCs belong to. You should get back the IP address of the 570master browser for that workgroup. 571</para> 572 573<para> 574If you do not, then the election process has failed. Wait a minute to 575see if it is just being slow, then try again. If it still fails after 576that, then look at the browsing options you have set in &smb.conf;. Make 577sure you have <smbconfoption name="preferred master">yes</smbconfoption> to ensure that 578an election is held at startup. 579</para> 580 581</step> 582 583<step performance="required"> 584 585<para> 586From file manager, try to browse the server. Your Samba server should 587appear in the browse list of your local workgroup (or the one you 588specified in &smb.conf;). You should be able to double-click on the name 589of the server and get a list of shares. If you get the error message <quote>invalid password,</quote> 590 you are probably running Windows NT and it 591is refusing to browse a server that has no encrypted password 592capability and is in user-level security mode. In this case, either set 593<smbconfoption name="security">server</smbconfoption> and 594<smbconfoption name="password server">Windows_NT_Machine</smbconfoption> in your 595&smb.conf; file or make sure <smbconfoption name="encrypt passwords"/> is 596set to <quote>yes</quote>. 597</para> 598 599</step> 600</procedure> 601</sect1> 602 603</chapter> 604