Updated by Patrick Powell <papowell@lprng.org>

(This used to be commit 3361c144f5ba2a87a469436f670ab35189021d49)

1 files changed, 195 insertions, 106 deletions

diff --git a/docs/textdocs/Printing.txt b/docs/textdocs/Printing.txt
index 358eab3b60..47729bcdff 100644
--- a/docs/textdocs/Printing.txt
+++ b/docs/textdocs/Printing.txt
@@ -1,8 +1,6 @@
-!==
-!== Printing.txt for Samba release 2.0.4 18 May 1999
-!==
 Contributor:	Unknown <samba-bugs@samba.org>
-Date:		Unknown
+Revised by:	Patrick Powell <papowell@lprng.org>
+Date:		August 11, 2000
 Status:		Current
 
 Subject:	Dubugging Printing Problems
@@ -25,125 +23,216 @@ 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
+      [global]
+        print command     - send a file to a spooler
+        lpq command       - get spool queue status
+        lprm command      - remove a job
+      [printers]
+        path = /var/spool/lpd/samba
 
-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.
+The following are nice to know about:
 
-On my system I use the following settings:
+        queuepause command   - stop a printer or print queue
+        queueresume command  - start a printer or print queue
 
-        print command = lpr -r -P%p %s
-        lpq command = lpq -P%p
-        lprm command = lprm -P%p %j
+Example:
+        print command = /usr/bin/lpr -r -P%p %s
+        lpq command   = /usr/bin/lpq    -P%p %s
+        lprm command  = /usr/bin/lprm   -P%p %j
+        queuepause command = /usr/sbin/lpc -P%p stop
+        queuepause command = /usr/sbin/lpc -P%p start
 
-The % bits are "macros" that get dynamically replaced with variables
-when they are used. The %s gets replaced with the name of the spool
+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.  The commands should
+always have fully specified pathnames,  as the smdb may not have
+the correct PATH values.
+
+When you send a job to Samba to be printed,  it will make a temporary
+copy of it in the directory specified in the [printers] section.
+and it should be periodically cleaned out.  The lpr -r option
+requests that the temporary copy be removed after printing; If
+printing fails then you might find leftover files in this directory,
+and it should be periodically cleaned out.  Samba used the lpq
+command to determine the "job number" assigned to your print job
+by the spooler.
+
+The %<letter> are "macros" that get dynamically replaced with appropriate
+values 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:
+DEBUGGING PRINTER PROBLEMS
+
+One way to debug printing problems is to start by replacing these
+command with 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 = /tmp/saveprint %p %s
+
+    #!/bin/saveprint
+    # we make sure that we are the right user
+    /usr/bin/id -p >/tmp/tmp.print
+    # we run the command and save the error messages
+    # replace the command with the one appropriate for your system
+    /usr/bin/lpr -r -P$1 $2 2>>&/tmp/tmp.print
+
+Then you print a file:
+
+    echo "print /tmp/test" |
+        smbclient //server/pr password -Uuser
+
+You can observe the command output and then and look at the
+/tmp/tmp.print file to see what the results are.  You can quickly
+find out if the problem is with your printing system.  Often people
+have problems with their /etc/printcap file or permissions on
+various print queues.
+
+WHAT PRINTERS DO I HAVE
+
+You can use the 'testprns' program to check to see if the printer
+name you are using is recognized by Samba.  For example,  you can
+use:
+
+    testprns printer /etc/printcap
+
+Samba can get its printcap information from a file or from a program.
+You can try the following to see the format of the extracted
+information:
+
+    testprns -a printer /etc/printcap
+
+    testprns -a printer '|/bin/cat printcap'
+
+SETTING UP PRINTCAP AND PRINT SERVERS
+
+You may need to set up some printcaps for your Samba system to use.
+It is strongly recommended that you use the facilities provided by
+the print spooler to set up queues and printcap information.
+
+Samba requires either a printcap or program to deliver printcap
+information.  This printcap information has the format:
+
+  name|alias1|alias2...:option=value:...
+
+For almost all printing systems, the printer 'name' must be composed
+only of alphanumeric or underscore '_' characters.  Some systems also
+allow hyphens ('-') as well.  An alias is an alternative name for the
+printer,  and an alias with a space in it is used as a 'comment'
+about the printer.  The printcap format optionally uses a \ at the end of lines
+to extend the printcap to multiple lines.
+
 
-	print command = cp %s /tmp/tmp.print
+Here are some examples of printcap files:
 
-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 the problem is with your lpr system, not with Samba. Often
-people have problems with their /etc/printcap file or permissions on
-various print queues. 
+pr              just printer name
+pr|alias        printer name and alias
+pr|My Printer   printer name, alias used as comment
+pr:sh:\        Same as pr:sh:cm= testing
+  :cm= \ 
+  testing
+pr:sh           Same as pr:sh:cm= testing
+  :cm= testing
 
-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.
+Samba reads the printcap information when first started.  If you make
+changes in the printcap information, then you must do the following:
 
-Other really common problems:
+a)  make sure that the print spooler is aware of these changes.
+    The LPRng system uses the 'lpc reread' command to do this.
 
-- 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"
+b)  make sure that the spool queues, etc., exist and have the
+    correct permissions.  The LPRng system uses the 'checkpc -f'
+    command to do this.
 
-- the user that the PC is trying to print as doesn't have permission
-to print. Fix your lpr system.
+c)  You now should send a SIGHUP signal to the smbd server to have
+    it reread the printcap information.
 
-- you get an extra blank page of output. Fix this in your lpr system,
-probably by editing /etc/printcap. It could also be caused by
-incorrect setting on your client. For example, under Win95 there is a
-option Printers|Printer Name|(Right
-Click)Properties|Postscript|Advanced| that allows you to choose if a
-Ctrl-D is appended to all jobs. This will affect if a blank page is
-output. 
+JOB SENT, NO OUTPUT
 
-- 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.
+This is the most frustrating part of printing.  You may have sent the
+job,  verified that the job was forwarded,  set up a wrapper around
+the command to send the file,  but there was no output from the printer.
+
+First,  check to make sure that the job REALLY is getting to the
+right print queue.  If you are using a BSD or LPRng print spooler,
+you can temporarily stop the printing of jobs.  Jobs can still be
+submitted, but they will not be printed.  Use:
+
+  lpc -Pprinter stop
+
+Now submit a print job and then use 'lpq -Pprinter' to see if the
+job is in the print queue.  If it is not in the print queue then
+you will have to find out why it is not being accepted for printing.
+
+Next, you may want to check to see what the format of the job really
+was.  With the assistance of the system administrator you can view
+the submitted jobs files.  You may be surprised to find that these
+are not in what you would expect to call a printable format.
+You can use the UNIX 'file' utitily to determine what the job
+format actually is:
+
+    cd /var/spool/lpd/printer   # spool directory of print jobs
+    ls                          # find job files
+    file dfA001myhost
+
+You should make sure that your printer supports this format OR that
+your system administrator has installed a 'print filter' that will
+convert the file to a format appropriate for your printer.
+
+JOB SENT, STRANGE OUTPUT
+
+Once you have the job printing, you can then start worrying about
+making it print nicely.
+
+The most common problem is extra pages of output: banner pages
+OR blank pages at the end.
+
+If you are getting banner pages,  check and make sure that the
+printcap option or printer option is configured for no banners.
+If you have a printcap,  this is the :sh (suppress header or banner
+page) option.  You should have the following in your printer.
+
+   printer: ... :sh
+
+If you have this option and are still getting banner pages,  there
+is a strong chance that your printer is generating them for you
+automatically.  You should make sure that banner printing is disabled
+for the printer.  This usually requires using the printer setup software
+or procedures supplied by the printer manufacturer.
+
+If you get an extra page of output,  this could be due to problems
+with your job format,  or if you are generating PostScript jobs,
+incorrect setting on your printer driver on the MicroSoft client.
+For example, under Win95 there is a option:
+
+  Printers|Printer Name|(Right Click)Properties|Postscript|Advanced|
+
+that allows you to choose if a Ctrl-D is appended to all jobs.
+This is a very bad thing to do, as most spooling systems will
+automatically add a ^D to the end of the job if it is detected as
+PostScript.  The multiple ^D may cause an additional page of output.
+
+RAW POSTSCRIPT PRINTED
+
+This is a problem that is usually caused by either the print spooling
+system putting information at the start of the print job that makes
+the printer think the job is a text file, or your printer simply
+does not support PostScript.  You may need to enable 'Automatic
+Format Detection' on your printer.
+
+ADVANCED PRINTING
 
 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. 
+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.
-
-=====================================================================
-From Caldera Inc., the following documentation has been
-contributed. Note that it contains stuff that is only relevant on some
-systems (specifically Caldera OpenLinux systems).
-
-
-8.6 Setting up a raw SAMBA printer.
-
-Note: this is not a guide on setting up SAMBA. It merely addresses
-creating a printer configuration that will allow the output of regular
-(i.e. not PostScript) Windows printer drivers to print through SAMBA.
-
-Regular Windows printer drivers can be used to print via SAMBA, but
-you must set up a raw printer entry in "/etc/printcap" to accomplish
-this. Also, a print command will need to be specified in
-"/etc/smb.conf" that forces binary printing.
-
-The best way to start is to use printtool under X to create a new
-entry specifically for this printer. All you really need for it to do
-is create the necessary directories and set the permissions correctly,
-so don't worry about setting up a filter for a specific printer.
-Filters are not going to be used at all for this entry.
-
-Next, go into "/etc" and edit the printcap entry you just created,
-changing it to look like this (if you named it something other than
-raw, the entry name and spool directory should be changed here to
-match):
-
-raw:\
-	:rw:sh: \
-	:lp=/dev/lp1: \
-	:sd=/var/spool/lpd/raw: \
-	:fx=flp:
-
-When this is done and saved, edit the section of the smb.conf file
-that applies to the printer. Make sure the name of the section
-(enclosed in brackets) matches the name of the raw printer you just
-set up, then go down a line or two and add this line:
- 
-print command = lpr -b -P%p %s
-
-Save the file, change to "/etc/rc.d/init.d", and type the following
-commands to restart the necessary daemons:
-
-./lpd stop
-./lpd start
-./smb stop
-./smb start
-
-At this point you should be ready to use the various printer drivers on
-your Windows clients for printing.
-=============================================================================
+DEBUGGING
 
+If the above debug tips don't help, then maybe you need to bring in
+the bug guns, system tracing. See Tracing.txt in this directory.
+-----------------------------------------------------------------------------