debian/README.Debian

   1 cups for Debian
   2 ----------------------
   3
   4 If you found a problem, please read HOWTO_BUGREPORT.txt and report me
   5 via Debian Bug Tracking System.
   6 --
   7 Kenshi Muto
   8 kmuto@debian.org
   9
  10 ---------
  11 This package contains the Common UNIX Printing System(tm), or CUPS(tm)
  12 for short.  CUPS is a new printing system for Unix that acts as a
  13 substitute for System V or BSD printing systems; it supports a more
  14 comprehensive driver model, more protocols, and Web administration,
  15 among other things.  Internally, CUPS uses the new Internet Printing
  16 Protocol (IPP) described in RFCs 2565 through 2569.
  17
  18 The terms "CUPS" and "Common UNIX Printing System" are trademarks of
  19 Easy Software Products, the author of the system.  This package is a
  20 derivative of the CUPS system, modified for Debian and possibly
  21 containing modifications and fixes that are not present in the
  22 standard CUPS package.  For a comprehensive list of changes from the
  23 original source, see the diff file from the source package.  For more
  24 information about the legal stuff surrounding this package, see the
  25 Debian copyright file or the CUPS Web site (www.cups.org).
  26
  27 After installation, CUPS is pretty close to being ready to go.  The
  28 last step is to add administrative access; the "lpadmin" group has
  29 been created and granted administrative rights to CUPS.  You may need
  30 to add users to this group in order to add printers, modify settings,
  31 etc.  By default, the root user has been granted this permission, but
  32 you should only use the root user on the local system.
  33
  34 The printers can be added with either the lpadmin program or the web
  35 interface, which is located at http://localhost:631/admin by default.
  36
  37 Backend Configuration
  38 ---------------------
  39
  40 CUPS supports serial, parallel, USB, SCSI, IPP, HTTP, Socket and Samba
  41 for its backend. But unfortunately, some backends cause a trouble.
  42 For example, serial backend confuses and won't stop when non printer
  43 device connects serial port. Parallel backend is more terrible for PPC,
  44 it may cause kernel crash (kernel bug, sigh).
  45 So, CUPS setting puts serial and SCSI off from backend by default. And
  46 if you use PPC, parallel backend is off also.
  47
  48 If you want to use these backends, you can configure by using
  49 'dpkg-reconfigure cups'.
  50
  51 SSL Support
  52 -----------
  53
  54 CUPS supports SSL via the OpenSSL toolkit, but licensing conflicts
  55 between OpenSSL's license and the GPL make this combination difficult
  56 to use, even though the CUPS license itself allows this.  A competing
  57 library, GNU TLS, has an OpenSSL compatibility layer that could work
  58 with these packages, but the compatibility library is licensed under
  59 the GNU GPL, which could conflict with the license of certain programs
  60 that support CUPS.  Therefore, the cups packages as shipped do not
  61 support SSL.
  62
  63 It is possible to build the packages yourself with SSL support.  You
  64 can either use the OpenSSL libraries or GNU TLS's OpenSSL
  65 compatibility library.  Just set an environment variable:
  66 "CUPS_OPENSSL" for OpenSSL support, or "CUPS_GNUTLS" for GNU TLS
  67 support, and make sure you have the proper development packages
  68 installed (libssl-dev for OpenSSL or libgnutls7-dev for GNU TLS).
  69
  70 PLEASE NOTE: If you build packages with SSL support and distribute
  71 them, you are responsible for making sure you do not violate the
  72 licenses of any of the software you distribute.
  73
  74 Important Security Notes
  75 ------------------------
  76
  77  - By default, cups is configured to only allow connections to
  78    printers from localhost, effectively disabling network printing.
  79    The previous default was to allow anyone to connect to printers
  80    from any location.  You can change these defaults by editing
  81    /etc/cups/cupsd.conf; the access controls are at the end of the
  82    file.  Be sure you only allow access from the locations you trust,
  83    or require authentication.
  84
  85  - CUPS used to support a file backend that was handled internally by
  86    cupsd.  This was only intended to be used for testing filters, and
  87    not in production use, as it can be a security risk and will drop
  88    jobs under certain circumstances.  In keeping with that, the file
  89    "backend" has been renamed to "test", and the lpadmin command no
  90    longer rewrites bare path URIs (either to "file:" or "test:").  If
  91    you need a backend that dumps a completed job to a file on the
  92    filesystem, you should write a separate backend and put it in
  93    /usr/lib/cups/backend.  See the CUPS documentation for information
  94    on how to do this.
  95
  96  - To relieve the burden of local authentication somewhat, CUPS uses
  97    special tokens called "certs" that are passed between client and
  98    server.  In normal CUPS installations, these are stored in
  99    /etc/cups/certs.  However, this location violates Debian policy, as
 100    the certs are generated and not available to edit.  Thus, the real
 101    certs are now stored in /var/spool/cups/certs, with a symlink at
 102    /etc/cups/certs for compatibility.
 103
 104 Drivers
 105 -------
 106
 107 The CUPS software includes generic drivers for several brands of
 108 printers.  At the moment, this includes HP LaserJets and DeskJets,
 109 various Epson and Okidata printers, and Dymo label printers.
 110
 111 There are also other packages containing CUPS printer drivers.  If any
 112 of those were written explicitly for your printer, chances are that it
 113 will support your printer better than the generic drivers that ship
 114 with CUPS.  I try to keep the package Suggestions current regarding
 115 popular CUPS driver packages; to see this list, run this command:
 116
 117   apt-cache show cups | grep Suggests
 118
 119 PostScript printers often ship with PPD files supplied by the printer
 120 manufacturer.  Any valid PPD for a PostScript printer is a valid CUPS
 121 driver.  To enable them for use with CUPS, copy the PPDs into
 122 /usr/share/cups/model; they should then be available for use with
 123 lpadmin -m and the Web interface for adding printers.
 124
 125 If you find a CUPS driver that isn't packaged for Debian and you'd
 126 like it to be, you can contact me and let me know where the driver is,
 127 and I'll get to it as soon as I can.
 128
 129 Or, you can package them yourself.  See below for details.
 130
 131 Packaging
 132 ---------
 133
 134 There are five packages provided by CUPS: the server, the primary
 135 command-line client programs, the BSD client and server compatibility
 136 programs, and the library and development packages.
 137
 138 The CUPS BSD commands and cups-lpd daemon are separated into their own
 139 package (cups-bsd); the hope is to make it possible to run CUPS and
 140 some other BSD-style printing system (such as lpr) side-by-side for
 141 testing purposes.  If you encounter any trouble doing this, file a
 142 bug.  It's known that CUPS conflicts with LPRng, since LPRng provides
 143 some System V printing commands as well; this problem will (hopefully)
 144 be dealt with in time.
 145
 146 Add-ons for CUPS (such as drivers, backends, clients, etc.) should
 147 depend on the proper packages.  If your package is CUPS-specific, you
 148 should name it so it can be easily identified as a CUPS package, with
 149 names such as:
 150
 151   cups-driver-foo       (for a driver for Foo printers)
 152   cups-backend-bar      (for a backend to print to Bar printers)
 153   cups-client-baz       (for a client module to hook Baz into CUPS)
 154
 155 If you feel your driver/backend/client/whatever package is popular
 156 enough that most CUPS users would be interested in it, please file a
 157 wishlist bug against cups requesting that it be added to the
 158 Suggests line for cups.
 159
 160 Other Add-Ons
 161 -------------
 162
 163 I'm also collecting add-ons - filters, backends, etc. - and putting
 164 them in the "examples" directory with the rest of the cups package
 165 documentation files.  Check there for some interesting filters and
 166 backends.
 167
 168 To install a filter from the filters directory, copy the filter itself
 169 into /usr/lib/cups/filter and the associated .types and .convs files
 170 into /etc/cups.  Then restart cupsd, and you should be ready to use
 171 it.
 172
 173 If you have a filter or backend you'd like to contribute, but don't
 174 think it's big enough to warrant its own package, file a wishlist bug
 175 and attach your script.  If it's a filter, send along a .convs and
 176 .types file as well.
 177
 178 Integration with Samba
 179 ----------------------
 180
 181 It is possible to configure Samba to share CUPS printers to Microsoft
 182 clients.  There are two ways to do this:
 183
 184 1.  Recent versions of Samba have direct CUPS support, including
 185 Debian's.  With this present, you can configure Samba as follows:
 186
 187 [global]
 188   printing = cups
 189   printcap name = cups
 190
 191 2.  If, for some reason, you don't want to use Samba's native CUPS
 192 support, you can configure Samba to use System V printing.  This can
 193 be done by adding the following information to Samba's smb.conf
 194 (/etc/samba/smb.conf on Debian):
 195
 196 [global]
 197   printing = sysv
 198   printcap name = lpstat
 199
 200 [printers]
 201   lpq command = /usr/bin/lpstat %p
 202   lprm command = /usr/bin/cancel %p-%j
 203   print command = /usr/bin/lp -d%p -oraw %s ; /bin/rm -f %s
 204
 205 This method will require installation of the cups-client package.
 206
 207 For more tips on integration with Samba, check out the man page for
 208 cupsaddsmb, which is part of the cups-client package.
 209
 210 Miscellaneous Tips
 211 ------------------
 212
 213  - CUPS has support for browsing, which uses broadcast traffic to
 214    auto-discover other CUPS servers and printers and make them
 215    available to clients.  In the default configuration, cupsd will
 216    accept browse packets in the CUPS format from other CUPS servers,
 217    but will not send any.  If sending browse packets is turned on, it
 218    may trigger demand dialers and increase traffic on the network.  To
 219    help prevent this, set the BrowseAddress parameter to only
 220    advertise CUPS printers on specific interfaces.  As a potentially
 221    more robust option, CUPS also supports SLP (Service Location
 222    Protocol).
 223
 224  - You may encounter some problems using the "enable" command under
 225    bash, as "enable" is a builtin there.  As a workaround, I've
 226    created the "cupsenable" command, which acts exactly as "enable"
 227    does.  There are also "cupsdisable", "cupsaccept", and "cupsreject"
 228    commands for consistency.
 229
 230  - There is an online database with PPDs for lots of different
 231    printers at http://www.linuxprinting.org/.  These will often
 232    require the "cupsomatic" utility; this can be found in the
 233    foomatic-bin package. Another case, some PPDs require the
 234    "foomatic-rip" utility; this can be found in the
 235    foomatic-filters package (this package will be installed when you
 236    install foomatic-filters-ppds package).
 237
 238  - Default location of pid file is /var/run/cups/cupsd.pid.
 239    If you'd like to change this, you can modify by using
 240    "PidFile <filepath>" directive at your /etc/cups/cupsd.conf.
 241
 242 Enjoy!
 243
 244  -- Jeff Licquia <licquia@debian.org> and Kenshi Muto <kmuto@debian.org>