diff options
| -rw-r--r-- | docs/docbook/devdoc/Tracing.sgml | 129 |
1 files changed, 129 insertions, 0 deletions
diff --git a/docs/docbook/devdoc/Tracing.sgml b/docs/docbook/devdoc/Tracing.sgml new file mode 100644 index 0000000000..3a0e4ba1a9 --- /dev/null +++ b/docs/docbook/devdoc/Tracing.sgml @@ -0,0 +1,129 @@ +<chapter id="tracing"> +<chapterinfo> + <author> + <firstname>Andrew</firstname><surname>Tridgell</surname> + <affiliation> + <orgname>Samba Team</orgname> + </affiliation> + </author> +</chapterinfo> + +<title>Tracing samba system calls</title> + +<para> +This file describes how to do a system call trace on Samba to work out +what its doing wrong. This is not for the faint of heart, but if you +are reading this then you are probably desperate. +</para> + +<para> +Actually its not as bad as the the above makes it sound, just don't +expect the output to be very pretty :-) +</para> + +<para> +Ok, down to business. One of the big advantages of unix systems is +that they nearly all come with a system trace utility that allows you +to monitor all system calls that a program is making. This is +extremely using for debugging and also helps when trying to work out +why something is slower than you expect. You can use system tracing +without any special compilation options. +</para> + +<para> +The system trace utility is called different things on different +systems. On Linux systems its called strace. Under SunOS 4 its called +trace. Under SVR4 style systems (including solaris) its called +truss. Under many BSD systems its called ktrace. +</para> + +<para> +The first thing you should do is read the man page for your native +system call tracer. In the discussion below I'll assume its called +strace as strace is the only portable system tracer (its available for +free for many unix types) and its also got some of the nicest +features. +</para> + +<para> +Next, try using strace on some simple commands. For example, <command>strace +ls</command> or <command>strace echo hello</command>. +</para> + +<para> +You'll notice that it produces a LOT of output. It is showing you the +arguments to every system call that the program makes and the +result. Very little happens in a program without a system call so you +get lots of output. You'll also find that it produces a lot of +"preamble" stuff showing the loading of shared libraries etc. Ignore +this (unless its going wrong!) +</para> + +<para> +For example, the only line that really matters in the <command>strace echo +hello</command> output is: +</para> + +<para><programlisting> +write(1, "hello\n", 6) = 6 +</programlisting></para> + +<para>all the rest is just setting up to run the program.</para> + +<para> +Ok, now you're familiar with strace. To use it on Samba you need to +strace the running smbd daemon. The way I tend ot use it is to first +login from my Windows PC to the Samba server, then use smbstatus to +find which process ID that client is attached to, then as root I do +<command>strace -p PID</command> to attach to that process. I normally redirect the +stderr output from this command to a file for later perusal. For +example, if I'm using a csh style shell: +</para> + +<para><command>strace -f -p 3872 >& strace.out</command></para> + +<para>or with a sh style shell:</para> + +<para><command>strace -f -p 3872 > strace.out 2>&1</command></para> + +<para> +Note the "-f" option. This is only available on some systems, and +allows you to trace not just the current process, but any children it +forks. This is great for finding printing problems caused by the +"print command" being wrong. +</para> + +<para> +Once you are attached you then can do whatever it is on the client +that is causing problems and you will capture all the system calls +that smbd makes. +</para> + +<para> +So how do you interpret the results? Generally I search through the +output for strings that I know will appear when the problem +happens. For example, if I am having touble with permissions on a file +I would search for that files name in the strace output and look at +the surrounding lines. Another trick is to match up file descriptor +numbers and "follow" what happens to an open file until it is closed. +</para> + +<para> +Beyond this you will have to use your initiative. To give you an idea +of what you are looking for here is a piece of strace output that +shows that <filename>/dev/null</filename> is not world writeable, which +causes printing to fail with Samba: +</para> + +<para><programlisting> +[pid 28268] open("/dev/null", O_RDWR) = -1 EACCES (Permission denied) +[pid 28268] open("/dev/null", O_WRONLY) = -1 EACCES (Permission denied) +</programlisting></para> + +<para> +The process is trying to first open <filename>/dev/null</filename> read-write +then read-only. Both fail. This means <filename>/dev/null</filename> has +incorrect permissions. +</para> + +</chapter> |