added Printing.txt and Tracing.txt

(This used to be commit 7b925230fc39e3286470e40f5467cbb524f335c3)

3 files changed, 168 insertions, 0 deletions

diff --git a/docs/textdocs/DIAGNOSIS.txt b/docs/textdocs/DIAGNOSIS.txt
index ad3eb44931..34099e6a16 100644
--- a/docs/textdocs/DIAGNOSIS.txt
+++ b/docs/textdocs/DIAGNOSIS.txt
@@ -240,4 +240,5 @@ Still having troubles?
 Try the mailing list or newsgroup, or use the tcpdump-smb utility to
 sniff the problem.
 
+Also look at the other docs in the Samba package!
 
diff --git a/docs/textdocs/Printing.txt b/docs/textdocs/Printing.txt
new file mode 100644
index 0000000000..93d1811512
--- /dev/null
+++ b/docs/textdocs/Printing.txt
@@ -0,0 +1,81 @@
+This is a short description of how to debug printing problems with
+Samba. This describes how to debug problems with printing from a SMB
+client to a Samba server, not the other way around. For the reverse
+see the examples/printing directory.
+
+Please send enhancements to this file to samba-bugs@samba.anu.edu.au
+
+Ok, so you want to print to a Samba server from your PC. The first
+thing you need to understand is that Samba does not actually do any
+printing itself, it just acts as a middleman between your PC client
+and your Unix printing subsystem. Samba receives the file from the PC
+then passes the file to a external "print command". What print command
+you use is up to you.
+
+The whole things is controlled using options in smb.conf. The most
+relevant options (which you should look up in the smb.conf man page)
+are:
+        print command
+        lpq command
+        lprm command
+
+Samba should set reasonable defaults for these depending on your
+system type, but it isn't clairvoyant. It is not uncommon that you
+have to tweak these for local conditions.
+
+On my system I use the following settings:
+
+        print command = lpr -r -P%p %s
+        lpq command = lpq -P%p
+        lprm command = lprm -P%p %j
+
+The % bits are "macros" that get dynamically replaced with variables
+when they are used. The %s gets replaced with the name of the spool
+file that Samba creates and the %p gets replaced with the name of the
+printer. The %j gets replaced with the "job number" which comes from
+the lpq output.
+
+When I'm debugging printing problems I often replace these command
+with pointers to shell scripts that record the arguments, and the
+contents of the print file. A simple example of this kind of things
+might be:
+
+	print command = cp %s /tmp/tmp.print
+
+then you print a file and look at the /tmp/tmp.print file to see what
+is produced. Try printing this file with lpr. Does it work? If not
+then your problem with with your lpr system, not with Samba. Often
+people have problems with their /etc/printcap file or permissions on
+various print queues. 
+
+Another common problem is that /dev/null is not world writeable. Yes,
+amazing as it may seem, some systems make /dev/null only writeable by
+root. Samba uses /dev/null as a place to discard output from external
+commands like the "print command" so if /dev/null is not writeable
+then nothing will work.
+
+Other really common problems:
+
+- lpr isn't in the search path when Samba tries to run it. Fix this by
+using the full path name in the "print command"
+
+- the user that the PC is trying to print as doesn't have permission
+to print. Fix your lpr system.
+
+- you get an extra blank page of output. Fix this in your lpr system,
+probably by editing /etc/printcap
+
+- you get raw postscript instead of nice graphics on the output. Fix
+this either by using a "print command" that cleans up the file before
+sending it to lpr or by using the "postscript" option in smb.conf.
+
+Note that you can do some pretty magic things by using your
+imagination with the "print command" option and some shell
+scripts. Doing print accounting is easy by passing the %U option to a
+print command shell script. You could even make the print command
+detect the type of output and its size and send it to an appropriate
+printer. 
+
+If the above debug tips don't help, then maybe you need to bring in
+the bug gun, system tracing. See Tracing.txt in this directory.
+
diff --git a/docs/textdocs/Tracing.txt b/docs/textdocs/Tracing.txt
new file mode 100644
index 0000000000..6a9ba8b850
--- /dev/null
+++ b/docs/textdocs/Tracing.txt
@@ -0,0 +1,86 @@
+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.
+
+Actually its not as bad as the the above makes it sound, just don't
+expect the output to be very pretty :-)
+
+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. 
+
+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. 
+
+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.
+
+Next, try using strace on some simple commands. For example, "strace
+ls" or "strace echo hello".
+
+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!)
+
+For example, the only line that really matters in the "strace echo
+hello" output is:
+
+write(1, "hello\n", 6)                  = 6
+
+all the rest is just setting up to run the program.
+
+Ok, now you're famialiar 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
+"strace -p PID" 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:
+
+  strace -f -p 3872 >& strace.out
+
+or with a sh style shell:
+
+  strace -f -p 3872 > strace.out 2>&1
+
+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.
+
+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. 
+
+So how do you interpret the results? Generally I search thorugh 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.
+
+Beyond this you will have to use your initiative. To give you an idea
+of wehat you are looking for here is a piece of strace output that
+shows that /dev/null is not world writeable, which causes printing to
+fail with Samba:
+
+[pid 28268] open("/dev/null", O_RDWR)   = -1 EACCES (Permission denied)
+[pid 28268] open("/dev/null", O_WRONLY) = -1 EACCES (Permission denied)
+
+the process is trying to first open /dev/null read-write then
+read-only. Both fail. This means /dev/null has incorrect permissions.
+
+Have fun!
+
+(please send updates/fixes to this file to samba-bugs@samba.anu.edu.au)