docs/devel/Tracing.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3                 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4   <!ENTITY % global_entities SYSTEM '../entities/global.entities'>
   5   %global_entities;
   6 ]>
   7 <chapter id="tracing">
   8 <chapterinfo>
   9         <author>
  10                 <firstname>Andrew</firstname><surname>Tridgell</surname>
  11                 <affiliation>
  12                         <orgname>Samba Team</orgname>
  13                 </affiliation>
  14         </author>
  15 </chapterinfo>
  16
  17 <title>Tracing samba system calls</title>
  18
  19 <para>
  20 This file describes how to do a system call trace on Samba to work out
  21 what its doing wrong. This is not for the faint of heart, but if you
  22 are reading this then you are probably desperate.
  23 </para>
  24
  25 <para>
  26 Actually its not as bad as the the above makes it sound, just don't
  27 expect the output to be very pretty :-)
  28 </para>
  29
  30 <para>
  31 Ok, down to business. One of the big advantages of unix systems is
  32 that they nearly all come with a system trace utility that allows you
  33 to monitor all system calls that a program is making. This is
  34 extremely using for debugging and also helps when trying to work out
  35 why something is slower than you expect. You can use system tracing
  36 without any special compilation options.
  37 </para>
  38
  39 <para>
  40 The system trace utility is called different things on different
  41 systems. On Linux systems its called strace. Under SunOS 4 its called
  42 trace. Under SVR4 style systems (including solaris) its called
  43 truss. Under many BSD systems its called ktrace.
  44 </para>
  45
  46 <para>
  47 The first thing you should do is read the man page for your native
  48 system call tracer. In the discussion below I'll assume its called
  49 strace as strace is the only portable system tracer (its available for
  50 free for many unix types) and its also got some of the nicest
  51 features.
  52 </para>
  53
  54 <para>
  55 Next, try using strace on some simple commands. For example, <command>strace
  56 ls</command> or <command>strace echo hello</command>.
  57 </para>
  58
  59 <para>
  60 You'll notice that it produces a LOT of output. It is showing you the
  61 arguments to every system call that the program makes and the
  62 result. Very little happens in a program without a system call so you
  63 get lots of output. You'll also find that it produces a lot of
  64 "preamble" stuff showing the loading of shared libraries etc. Ignore
  65 this (unless its going wrong!)
  66 </para>
  67
  68 <para>
  69 For example, the only line that really matters in the <command>strace echo
  70 hello</command> output is:
  71 </para>
  72
  73 <para><programlisting>
  74 write(1, "hello\n", 6)                  = 6
  75 </programlisting></para>
  76
  77 <para>all the rest is just setting up to run the program.</para>
  78
  79 <para>
  80 Ok, now you're familiar with strace. To use it on Samba you need to
  81 strace the running smbd daemon. The way I tend ot use it is to first
  82 login from my Windows PC to the Samba server, then use smbstatus to
  83 find which process ID that client is attached to, then as root I do
  84 <command>strace -p PID</command> to attach to that process. I normally redirect the
  85 stderr output from this command to a file for later perusal. For
  86 example, if I'm using a csh style shell:
  87 </para>
  88
  89 <para><command>strace -f -p 3872 &gt;&amp; strace.out</command></para>
  90
  91 <para>or with a sh style shell:</para>
  92
  93 <para><command>strace -f -p 3872 > strace.out 2&gt;&amp;1</command></para>
  94
  95 <para>
  96 Note the "-f" option. This is only available on some systems, and
  97 allows you to trace not just the current process, but any children it
  98 forks. This is great for finding printing problems caused by the
  99 "print command" being wrong.
 100 </para>
 101
 102 <para>
 103 Once you are attached you then can do whatever it is on the client
 104 that is causing problems and you will capture all the system calls
 105 that smbd makes.
 106 </para>
 107
 108 <para>
 109 So how do you interpret the results? Generally I search through the
 110 output for strings that I know will appear when the problem
 111 happens. For example, if I am having touble with permissions on a file
 112 I would search for that files name in the strace output and look at
 113 the surrounding lines. Another trick is to match up file descriptor
 114 numbers and "follow" what happens to an open file until it is closed.
 115 </para>
 116
 117 <para>
 118 Beyond this you will have to use your initiative. To give you an idea
 119 of what you are looking for here is a piece of strace output that
 120 shows that <filename>/dev/null</filename> is not world writeable, which
 121 causes printing to fail with Samba:
 122 </para>
 123
 124 <para><programlisting>
 125 [pid 28268] open("/dev/null", O_RDWR)   = -1 EACCES (Permission denied)
 126 [pid 28268] open("/dev/null", O_WRONLY) = -1 EACCES (Permission denied)
 127 </programlisting></para>
 128
 129 <para>
 130 The process is trying to first open <filename>/dev/null</filename> read-write
 131 then read-only. Both fail. This means <filename>/dev/null</filename> has
 132 incorrect permissions.
 133 </para>
 134
 135 </chapter>