LDP/LDP/howto/docbook/Debian-and-Windows-Shared-Printing/Debian-and-Windows-Shared-Printing.xml

<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article id="linux_windows_printing">
 <articleinfo>
  <title>Debian and Windows Shared Printing mini-HOWTO</title>
  <author>
   <firstname>Ian</firstname>
   <surname>Ward</surname>
   <affiliation>
    <address>
<email>ian at excess dot org</email>
    </address>
   </affiliation>
  </author>
  <pubdate>2002-12-01</pubdate>
  <revhistory>
   <revision>
    <revnumber>1.1</revnumber>
    <date>2003-06-26</date>
    <authorinitials>iw</authorinitials>
    <revremark>Added passwords on windows shared printers, Corrections</revremark>
   </revision>
   <revision>
    <revnumber>1.0</revnumber>
    <date>2003-05-15</date>
    <authorinitials>tmm</authorinitials>
    <revremark>Initial release, reviewed by LDP</revremark>
   </revision>
   <revision>
    <revnumber>0.8</revnumber>
    <date>2003-04-11</date>
    <authorinitials>iw</authorinitials>
    <revremark>converted from LaTeX</revremark>
   </revision>
  </revhistory>
 </articleinfo>
  
 <sect1 id="introduction">
  <title>Introduction</title>
  <para>
   Debian GNU/Linux 
   (<ulink url="http://www.debian.org">http://www.debian.org</ulink>)
is the premier volunteer-supported Linux distribution.
Unfortunately, setting up printers in Debian can be difficult. Also,
simple step-by-step instructions for sharing printers between Windows
and Linux using the latest tools are hard to find. This HOWTO was 
written to address both problems.
</para>
<para>
This HOWTO will demonstrate how to use command-line tools to configure your
Debian system for printing. It will explain how to send documents
from Linux to Windows printers and how to share Linux printers with
Windows PCs. Some troubleshooting examples are also given.
</para>
<para>
The primary url for this document is
<ulink url="http://excess.org/docs/linux_windows_printing.html">
http://excess.org/docs/linux_windows_printing.html</ulink>.
The source Docbook/XML and EPS files for this document may be downloaded from 
<ulink url="http://excess.org/docs/src/">
http://excess.org/docs/src/</ulink>.
Please forward bug reports, corrections and suggestions regarding this document
to ian at excess dot org.  
</para>

</sect1>
<sect1 id="getting_started">
<title>Getting Started</title>
<sect2 id="linuxprintingcomponents">
<title>Linux Printing Components</title>

<para>
The main components we will be using include:
<itemizedlist>
<listitem>
<para>
CUPS
</para>
<para>
The Common UNIX Printing System 
(<ulink url="http://www.cups.org">http://www.cups.org</ulink>)
is a print spooler and a set
of support programs for using and administering printers.
</para>
</listitem>
<listitem>
<para>
Samba
</para>
<para>
Samba 
(<ulink url="http://www.samba.org">http://www.samba.org</ulink>)
is software that allows non-Windows computers to act
like Windows computers on a network by implementing Windows file
and printer sharing protocols.
</para>
</listitem>
<listitem>
<para>
Printer Drivers
</para>
<para>
LinuxPrinting.org
(<ulink url="http://www.linuxprinting.org">http://www.linuxprinting.org</ulink>)
offers the largest number of printer drivers
and maintains a database of printers supported under Linux. You must
download a printer driver for each model of printer you want to use 
from Linux.  A printer driver consists of a PPD file and a filter
program, or only a PPD file for PostScript printers.
</para>
</listitem>
</itemizedlist>
</para>

</sect2>
<sect2 id="packages">
<title>Required Packages</title>

<para>
All of the required programs and libraries are part of the standard
Debian archive. You may download and install these packages with the
usual Debian packaging tools. The following is a list of packages
you need:
</para>
<variablelist>
<varlistentry>
<term>cupsys</term>
<listitem><para>CUPS server</para></listitem>
</varlistentry>
<varlistentry>
<term>cupsys-bsd</term>
<listitem><para>CUPS BSD commands</para></listitem>
</varlistentry>
<varlistentry>
<term>cupsys-client</term>
<listitem><para>CUPS client programs</para></listitem>
</varlistentry>
<varlistentry>
<term>foomatic-bin</term>
<listitem><para>LinuxPrinting.org printer support programs</para></listitem>
</varlistentry>
<varlistentry>
<term>samba</term>
<listitem><para>Samba SMB/CIFS server for UNIX</para></listitem>
</varlistentry>
<varlistentry>
<term>smbclient</term>
<listitem><para>Samba SMB/CIFS client for UNIX</para></listitem>
</varlistentry>
<varlistentry>
<term>gs-esp</term>
<listitem><para>ESP Ghostscript
(<ulink url="http://www.cups.org/ghostscript.php">
http://www.cups.org/ghostscript.php</ulink>)</para>
<remark>Only available in testing and unstable.  
Debian stable users must install <quote>gs</quote> instead</remark>
</listitem>
</varlistentry>
<varlistentry>
<term>a2ps</term>
<listitem><para>GNU A2PS
(<ulink url="http://www.gnu.org/software/a2ps/">
http://www.gnu.org/software/a2ps/</ulink>)</para></listitem>
</varlistentry>
</variablelist>

<para>
The following commands will install these packages:
</para>
<para>
<programlisting><![CDATA[apt-get update
apt-get install cupsys cupsys-bsd cupsys-client foomatic-bin samba smbclient gs-esp a2ps
]]></programlisting>
</para>
<para>
Additional packages may be required for specific printers. For example,
the <emphasis>hpijs</emphasis> package must be installed for HP InkJet printers
to function properly.
</para>

</sect2>
<sect2 id="basicprconfig">
<title>CUPS Local Printer Configuration</title>

<para>
The <command>lpadmin</command> command is used to configure printers. The
following is an example of setting up a laser printer with CUPS:
</para>

<programlisting><![CDATA[/usr/sbin/lpadmin -p Laser -v parallel:/dev/lp0 -P /root/laser.ppd
/usr/bin/enable Laser
/usr/sbin/accept Laser
/usr/sbin/lpadmin -d Laser
]]></programlisting>

<para>
The first command creates a new printer called <quote>Laser</quote>
that is connected to the first parallel port and is using the PPD 
file <filename>/root/laser.ppd</filename>.
<quote>Laser</quote> is then enabled and told to accept jobs with 
the <command>enable</command> and <command>accept</command> commands.
The last command sets <quote>Laser</quote> as the default printer. 
More detailed information about printer configuration
is available in the CUPS documentation.
</para>
      
</sect2>
<sect2 id="basics">
<title>Linux Printing Basics</title>

<figure id="printlocal">
<title>Printing Locally</title>
<graphic fileref="printing_basics.png"/>
</figure>

<para>
Documents are spooled by using either <command>lpr</command> or
<command>lp</command> followed
by the file name. You may view the printer queue and check the printer
status with the command <command>lpstat -o</command> or 
<command>lpstat -p</command>. To cancel a print job use either
<command>cancel</command> or <command>lprm</command> followed by the job id.
</para>
<para>
The CUPS spooler daemon is called <emphasis>cupsd</emphasis>. 
It converts documents
to PostScript, then converts them to a format native to the printer
<xref linkend="printlocal"/>. Printers that do not understand PostScript
use a rasterized, or bitmap, format for documents. Rasterized formats
can be much larger than the original PostScript, and will take longer
to send to the printer.
</para>
<para>
Filters are programs used to convert documents from one format to
another. The CUPS spooler will do its best to find a suitable filter
for the documents you send. If no filter suitable for converting your
document is installed you will receive an error similar to <computeroutput>lpr:
unable to print file: client-error-document-format-not-supported.</computeroutput>
</para>
<para>
Many applications do not include filters for their documents formats.
Documents created with these applications can only be printed from
within the application itself, unless the document is exported to
PostScript or another standard format.
</para>

</sect2>
</sect1>
<sect1 id="printing_to_windows">
<title>Printing To Windows PCs</title>

<sect2 id="to_windows">
<title>Connecting To Windows</title>

<figure id="netprint">
<title>Network Printing</title>
<graphic fileref="to_windows.png"/>
</figure>

<para>
SMB and CIFS are the Windows file and printer sharing protocols.
We use Samba to speak to the Windows PCs using these protocols. Before
configuring CUPS we should make sure we can connect to the Windows
PC with <command>smbclient</command>, the Samba SMB/CIFS client
<xref linkend="netprint"/>. 
</para>
<para>
The following is an example of creating a connection to a Windows
PC:

<programlisting><![CDATA[/usr/bin/smbclient -L rice -U fred

added interface ip=10.6.7.234 bcast=10.6.7.255 nmask=255.255.255.0
Got a positive name query response from 10.6.7.8 ( 10.6.7.8 )
Password: (not shown)

Sharename  Type  Comment
PRINTER$   Disk
INKJET     Printer
STUFF      Disk
IPC$       IPC    Remote Inter Process Communication 
]]></programlisting>
</para>
<para>
The command shown asks for a list of shares on a Windows PC
named <quote>rice</quote>, with the user id <quote>fred</quote>.
show a printer named <quote>INKJET</quote>. 
</para>
<para>
If Windows naming service is unavailable you will need to specify
the IP address of the Windows PC with the <option>-I</option> switch as in:

<programlisting><![CDATA[/usr/bin/smbclient -I 10.6.7.8 -L rice -N
]]></programlisting>
</para>
<para>
For more information see the Samba documentation about 
<command>smbclient</command> usage.
</para>

</sect2>
<sect2 id="to_windows_cupsconfig">
<title>CUPS Configuration</title>
<para>
Once you have found a Windows printer you may configure CUPS. First
verify that your installation of CUPS has the smb backend with the
following command:
<programlisting><![CDATA[ls -l /usr/lib/cups/backend/smb
]]></programlisting>
</para>
<para>
If this file does not exist create it by issuing the following:
<programlisting><![CDATA[ln -s `which smbspool` /usr/lib/cups/backend/smb
]]></programlisting>
</para>
<para>
The following is an example of setting up the printer shown above:
<programlisting><![CDATA[/usr/sbin/lpadmin -p RicePrinter -v smb://fred:mypass@rice/INKJET -P /root/inkjet.ppd
/usr/bin/enable RicePrinter
/usr/sbin/accept RicePrinter
/usr/sbin/lpadmin -d RicePrinter
]]></programlisting>
</para>
<para>
The <quote>lpadmin</quote> command sets up a the shared Windows printer by
giving the username, password, netbios name and printer name as a single
parameter.
See <xref linkend="basicprconfig"/> for a further explanation of the commands
above. If Windows naming service is unavailable, add the switch 
<option>-h</option> followed by the IP address of the Windows PC 
to the first <command>lpadmin</command> command as in:

<programlisting><![CDATA[/usr/sbin/lpadmin -p RicePrinter -h 10.6.7.8 -i smb://fred:mypass@rice/inkjet -P /root/inkjet.ppd
]]></programlisting>
</para>
<para>
Your printer is now ready to test. Send a file to the printer with
the <command>lp</command> command followed by a filename, or 
by printing a document from within an application.
</para>
      
</sect2>
</sect1>
<sect1 id="sharing_with_windows">
<title>Sharing Printers With Windows PCs</title>

<sect2 id="sharing_basics">
<title>Sharing Basics</title>

<figure id="printshare">
<title>Printer Sharing</title>
<graphic fileref="from_windows.png"/>
</figure>

<para>
Samba uses <emphasis>nmbd</emphasis> and <emphasis>smbd</emphasis> 
daemons to share files and printers with Windows PCs. 
<emphasis>nmbd</emphasis> acts as a Windows naming service,
broadcasting your computer's name to Windows PCs on the LAN. 
<emphasis>smbd</emphasis> accepts file and printer requests from 
Windows PCs <xref linkend="printshare"/>. 
</para>
<para>
You will need to download and install Windows printer drivers for
each Linux printer you are sharing. Windows printer drivers can be
found by searching the web site of your printer manufacturer. 
</para>

</sect2>
<sect2 id="share_samba_config">
<title>Samba Configuration</title>
<para>
If you are allowing anonymous access to your printer you will need
to create a user account for remote print jobs:

<programlisting><![CDATA[/usr/sbin/adduser --system --disabled-password smbprint
]]></programlisting>
</para>
<para>
This command adds a user called <quote>smbprint</quote> to your system. Make
sure there is enough disk space in <filename>/home/smbprint</filename>, the 
<quote>smbprint</quote> user's home directory, to spool files. Check 
that the <quote>smbprint</quote> user does not have permission on your 
system to read or modify sensitive files and directories. If you have 
configured CUPS to restrict printing to certain users on your system,
you must allow the <quote>smbprint</quote> user to access printers you
want to share.
</para>
<para>
The Samba configuration file is <filename>/etc/samba/smb.conf</filename>. 
The following is an example configuration file set up to use CUPS with 
the <quote>smbprint</quote> user:

<programlisting><![CDATA[[global]
  printcap name = cups  
  printing = cups   
  security = share   
[printers]   
  browseable = yes   
  printable = yes   
  public = yes   
  create mode = 0700   
  guest only = yes   
  guest account = smbprint   
  path = /home/smbprint   
]]></programlisting>
</para>
<para>
Please note that this configuration will allow printing by anyone
that can make a network connection to your computer and is
not recommended for computers on untrusted networks, such as
computers with direct Internet connections.  If you need to
implement access control, set <emphasis>security = user</emphasis> or 
<emphasis>security = domain</emphasis>
and read the Samba man pages for further information.
</para>
<para>
Once you have added the above settings to your Samba configuration
file you must restart Samba with the command:

<programlisting><![CDATA[/etc/init.d/samba restart
]]></programlisting>
</para>

</sect2>
<sect2 id="share_cups_config">
<title>CUPS Configuration</title>
<para>
Windows printer drivers format their output for the printer before
sending it across the network.  You must configure CUPS to accept
the pre-formatted output by uncommenting the following line from
<filename>/etc/cups/mime.convs</filename>:
<programlisting><![CDATA[application/octet-stream   application/vnd.cups-raw   0   -
]]></programlisting>
</para>
<para>
Also uncomment the following line from 
<filename>/etc/cups/mime.types</filename>:
<programlisting><![CDATA[application/octet-stream
]]></programlisting>
</para>
<para>
Now CUPS must be told to allow connections from other machines on
the network.  Add these lines to <filename>/etc/cups/cupsd.conf</filename>:
<programlisting><![CDATA[<Location /printers>
 AuthType None
 Order Deny,Allow
 Deny From None
 Allow From All
</Location>
]]></programlisting>
As in the Samba configuration, this configuration allows any computer
to connect to your printers and is not recommended for computers on
untrusted networks.  For information about tightening access control
to your printers, see the <filename>cupsd.conf</filename> man page
and the CUPS documentation.
</para>
<para>
Finally, restart cups with the following command:
<programlisting><![CDATA[/etc/init.d/cupsys restart
]]></programlisting>
</para>
<para>
Your Linux printers should now be shared to Windows PCs on the LAN.
Follow the usual steps for adding a network printer to your Windows
PCs, and remember to print a test page.
</para>

</sect2>
</sect1>
<sect1 id="troubleshooting">
<title>Troubleshooting</title>

<sect2 id="connect_failure">
<title>Failing To Connect To Windows Printers</title>
<para>
When <emphasis>smbspool</emphasis>, the 
<command>smbclient</command> utility CUPS uses,
fails to connect properly it emits error messages
that are humorous but not very helpful. One such message is <computeroutput>Unable
to connect to SAMBA host: Success.</computeroutput> Another sign of connection failures
is when documents seem to get stuck on the queue when printing to
Windows printers.
</para>
<para>
View the most recent entries in the CUPS log with the following command:

<programlisting><![CDATA[/usr/bin/tail /var/log/cups/error_log
]]></programlisting>
</para>
<para>
If you see a message similar to <computeroutput>cli_connect() failed...</computeroutput> then
<emphasis>smbspool</emphasis> could not find the Windows PC you are 
trying to connect to. 
Check the spelling of the Windows PC's host name. Check that the
Windows PC is turned on and that its network connection is functioning
properly. Make sure you can connect to it using 
<command>smbclient</command> as shown in <xref linkend="to_windows"/>.
</para>
<para>
If you see a message similar to <computeroutput>SMB tree connect failed: ERRSRV
- ERRinvnetname</computeroutput> then <command>smbclient</command> connected 
to the Windows PC
but could not connect to the printer you requested. Check the spelling
of the shared printer using <command>smbclient</command> as shown in 
<xref linkend="to_windows"/>.
</para>

</sect2>
<sect2 id="other_failure">
<title>Other Failures</title>
<para>
Other failures include being unable to print to a local printer and
having your print jobs disappear from the queue without being printed.
You may also see vague error messages such as <computeroutput>Child process 2384
exited with status 32.</computeroutput>
</para>
<para>
Increase CUPS' logging level to <quote>debug</quote> to see more messages about
what happened before the print job failed. 
</para>
<orderedlist>
<listitem>
<para>
Open the main CUPS configuration file <filename>/etc/cups/cupsd.conf</filename> in
a text editor.
</para>
</listitem>
<listitem>
<para>
Change the line that reads <quote>LogLevel warn</quote> to <quote>LogLevel debug</quote>.
</para>
</listitem>
<listitem>
<para>
Save the configuration file and exit the text editor.
</para>
</listitem>
<listitem>
<para>Restart the CUPS server with the command:

<programlisting><![CDATA[/etc/init.d/cupsys restart
]]></programlisting>
</para>
</listitem>
</orderedlist>

<para>
You can follow the CUPS log with the following command:

<programlisting><![CDATA[/usr/bin/tail -f /var/log/cups/error_log
]]></programlisting>
</para>
<para>
You should see a line that reads <computeroutput>Scheduler shutting down due to
SIGTERM</computeroutput>. This indicates that the CUPS server was stopped successfully. 
</para>
<para>
Send your print job again and watch for useful debug messages that
appear. One example of a useful debug message is <computeroutput>GNU Ghostscript
7.05: Can't start ijs server 'hpijs'.</computeroutput> In this case the solution
is to install the <quote>hpijs</quote> package.
</para>
<para>
If you cannot determine the cause of the failure, do an Internet search
for key terms in error messages you see; it is likely that someone
has solved your problem before. You may also try upgrading the packages
listed in <xref linkend="packages"/> to their latest versions.
</para>

</sect2>
</sect1>
<sect1 id="license">
<title>License</title>
<para>
Copyright &copy; 2003 Ian Ward.
</para>
<para>
This manual is free software; you may redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software 
Foundation; either version 2, or (at your option) any later version.
</para>
<para>
This is distributed in the hope that it will be useful, but without any 
warranty; without even the implied warranty of merchantability or fitness for
a particular purpose. See the GNU General Public License for more details.
</para>
<para>
A copy of the GNU General Public License is available as 
/usr/share/common-licenses/GPL in the Debian GNU/Linux distribution or on the
World Wide Web at http://www.gnu.org/copyleft/gpl.html. You can also obtain it
by writing to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
Boston, MA 02111-1307, USA. 
</para>

</sect1>
</article>