README
1Welcome to CUPS-PDF v3
2
3 CONTENTS:
4
5 1. building CUPS-PDF
6 2. setting up the PDF queue with CUPS
7 3. advanced configuration and multiple instances
8 4. note for MacOSX
9 5. contact
10
11
121. building CUPS-PDF
13--------------------
14
15 Edit src/cups-pdf.h if you do not like /etc/cups as location for your
16 configuration files.
17 To compile CUPS-PDF, invoke gcc in the src/ directory:
18
19 gcc -O9 -s cups-pdf.c -o cups-pdf -lcups
20
21 Note: you will have to have the deveopment package for CUPS installed
22 in order to build CUPS-PDF
23
24 To install the binary, simply copy cups-pdf to the backend directory
25 of CUPS (usually /usr/lib/cups/backend or /usr/lib64/...).
26
27 Now copy extra/cups-pdf.conf to /etc/cups (or whatever location you
28 selected in cups-pdf.h above). Here you can set all properties of
29 CUPS-PDF at runtime without the need for restarting any services.
30 (The defaults should work fine on most systems.)
31
32 If you want to use the color PostScript driver that comes with
33 CUPS-PDF go to the extra/ subdirectory and copy CUPS-PDF_opt.ppd to
34 your CUPS model directory (usually /usr/share/cups/model [ /Generic ] ).
35 If you do not want to set any options via PPD (see section 3), use
36 CUPS-PDF_noopt.ppd instead.
37
38
392. setting up the PDF queue with CUPS
40-------------------------------------
41
42 Important notes:
43 ================
44
45 * CUPS-PDF requires root privileges since it has to modify file ownerships.
46 In order to ensure CUPS-PDF is running with the required root privileges
47 you have to make 'root' the owner of the cups-pdf backend and set the
48 file permissions of the backend to 0700 (root only).
49 NOTE: in older versions of CUPS (<1.2.0) you have to set the "RunAsUser"
50 option in cupsd.conf to "No" in order to grant full privileges.
51 * CUPS-PDF needs a fully featured UNIX-filesystem to work. Make sure if any
52 of CUPS-PDF's working directories (e.g. output) are located on an NFS
53 mounted volume they are mounted without root_squash! Other filesystems
54 (e.g. NetWare or Windows shares as well as NFSv4 with kerberos) are _not_
55 supported!
56 * CUPS-PDF is known to fail if the gs (GhostScript) binary on a system is
57 compressed by upx (Ultimate Packer for eXecutables).
58 * If you are using SELinux, AppArmour or similar tools, make sure these do
59 not interfere with CUPS-PDF.
60 (You can disable SELinux for CUPS by "setsebool -P cupsd_disable_trans 1"
61 or have a look at the SELinux-HOWTO on www.cups-pdf.de)
62
63 Now you will be able to choose "CUPS-PDF (Virtual PDF Printer)" when
64 setting up a new printer in CUPS (a CUPS-restart may be necessary).
65 To set up a queue for other UNIX clients you should select Postscript as
66 vendor and the Color Printer as model for your new printer; queues that get
67 their input from samba or netatalk (i.e. Windows, OS/2 or MacOS) can be set
68 up as raw queues. On the Windows, OS/2 or MacOS system choose a color
69 postscript driver for that network printer (the drivers for Minolta Page
70 Works or HP DesignJet printers do a good job).
71 Hint: If you want to create grayscale PDFs you just have to choose a
72 grayscale printer driver, i.e. the postscript.ppd that comes with CUPS on
73 the Linux side or a b/w laser printer (e.g. a HP LaserJet) on the Windows
74 side. On the Linux side be aware that the postscript.ppd will not
75 re-process data that is already supplied in Postscript format, i.e. a color
76 Postscript will keep it's colors.
77
78 Once you print to the new device the output directory selected in
79 cups-pdf.conf (defaults to /var/spool/cups-pdf) will be created and all
80 converted PDF files will be placed in subdirectories named after the owner
81 of the print job. In case the owner cannot be identified (i.e. does not
82 exist on the server) the output is placed in the directory for anonymous
83 operation (if not disabled in cups-pdf.conf - defaults to
84 /var/spool/cups-pdf/ANONYMOUS/).
85 Furthermore if logging is enabled the logfile will be placed by default in
86 /var/log/cups.
87
88 The files "CUPS-PDF_opt.ppd" and "CUPS-PDF_noopt.ppd" are modified versions
89 of the "Postscript.ppd.gz" that comes with CUPS 1.1.15 that is able to
90 handle color output.
91
92 You should have a look at the contributed software on www.cups-pdf.de which
93 contains several additions to CUPS-PDF which enhance functionality or
94 supports the setup of CUPS-PDF on different platforms.
95
96
973. advanced configuration and multiple instances
98------------------------------------------------
99
100 CUPS-PDF now has a PPD file (CUPS-PDF_opt.ppd) that allows setting the following
101 options in the CUPS webinterface (administration/set default options):
102 - resolution
103 - page size
104 - PDF version
105 - truncate output file names
106 - labelling (with jobid) of output files
107 - title source preference
108 - log level
109 Please note that setting these options in the cups-pdf.conf will have no
110 effect if you use the included PPD file as the settings from the PPD-file
111 will override the settings in the config file.
112
113 Additionally users can set some of the options using lpoptions (see man lpoptions):
114 - PDFVer
115 - PostProcessing
116 - Cut
117 - Truncate
118 - TitelPref
119 - UserMask
120 See the configfile for an overview of the options and their meanings.
121 These options are deemed not to create security risks.
122 If you insist on allowing users to set other options as well (creating security risks,
123 you have been warned!), set AllowUnsafeOptions in the config file
124 (/etc/cups/cups-pdf.conf) to 1.
125
126 To create multiple instances of the backend with different configurations, simply
127 copy several config files in your config directory, naming them
128 cups-pdf-<NAME>.conf, where <NAME> is a unique identifier for this instance.
129 You can then select the new instances as URI when creating a new printer in CUPS.
130
131
1324. note for MacOSX
133------------------
134
135 Since MacOSX' AFPL GhostScript does not support the way of PDF generation
136 used by CUPS-PDF you will have to use pstopdf instead. For this the
137 settings of GhostScript, GSCall and PDFVer in cups-pdf.conf have to be
138 changed accordingly. The values are documented in cups-pdf.conf .
139
140
1415. contact
142----------
143
144 Volker C. Behr
145 volker@cups-pdf.de
146 http://www.cups-pdf.de
147
148