docs/docbook/projdoc/Diagnosis.sgml

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