[last modified: 2008.05.15]

Notes on CUPS and print-to-email configuration

Below some notes on how to configure CUPS (1.3.7) and CUPS-PDF (2.4.7) to implement a print-to-email service with Windows systems.

Overall the system is very simple, and similar to the 'gigamail' service that some ISP offer:
[Windows] clients install a Network Printer, using their own email address as username. When printing to this printer, the server will create a PDF file, place it on the web server at a private URL, and email the URL to the client who made the print. This way, the file can be exchanged easily, without hitting email or virus filters.

Client configuration

On Windows XP clients, do the following:

go to the 'Printer and faxes' menu ("start"->"Printers and Faxes");
select 'Add a printer' on the top of the menu on the left;
on the Wizard select 'Next',
click 'A network printer', then 'Next' again,
click on 'Connect to a printer on the internet...' and in the URL write
http://xxx.yyy.zzz:631/printers/CUPS-PDF
(where xxx.yyy.zzz is the name of the server, ask your sysadmin) and then 'Next'
Click on 'Use the specified user account', in the UserName field put your email address, and in the password field put the password that your administrator gave you, then click 'Ok'.
NOTE: If you are on Windows XP behind a proxy, you cannot pass authentication information this way, so you need to patch CUPS as described below, and specify the printer URL as
http://xxx.yyy.zzz:631/printers/CUPS-PDF::your@email.address
The page asking you for username will not appear so make sure you have typed the correct address. Also, make sure you have applied proper restrictions for accessing the resouce e.g. only allow requests coming from the proxy's public IP.
Now select a printer driver (use any Color Postscript driver should work): select 'Apple' in the manufacturer window, and then 'Apple Color LW 12/660 PS' (or similar e.g. 12/600) in the 'Printers' window. Then press 'OK'.
'Default printer':, leave 'No' selected and click 'Next'

You are done, the new printer is installed. Now, when you print to the 'CUPS-PDF' printer, you will receive an email with a link to the document that you printed. You can then download the document with a browser, or communicate the link to someone else who needs to access the file.

XP bugs when connecting to a CUPS printer

During our experiments we found the following bugs in the printer subsystem in Windows XP (both the base version and SP2). This affects users that 1) need to go through a proxy to connect to the CUPS server, and 2) need authentication.
In detail:

if you configure "Internet Options" to use a proxy, the driver will use the proxy only for non-authenticated requests.
When the CUPS server responds with a 401 or 407 code asking for authentication and presenting a challenge, windows will stop using the proxy, and try to talk directly to the server. This has been verified with a tcpdump on the client's output interface and also looking at the web server's logs.
The same problem occurs if communication is done via https.

On Windows there is no known workaround so far. There is a related thread on the CUPS mailing list.

As a CUPS workaround, we apply this patch to cups/http-support.c to accept URIs of the form

http://server:port/resource::username

and terminate the resource at the '::' marker, with the remaining part constituting the username (which can be an email address).

Server configuration

This section is intended for the system administrator.

We use the 'cups-base' and 'cups-pdf' packages on FreeBSD, with small modifications.

In the cupsd.conf configuration file, add an entry for the CUPS-PDF printer, e.g. as follows (note, because of the above bug, you cannot use encryption or authentication on Windows behind a proxy).

<Location /printers/CUPS-PDF>
  # NOTE, the following 3 lines won't work on windows behind a proxy
  # Encryption Required # uncomment this if you want encryption.
  AuthType BasicDigest  # lookup in passwd.md5
  Require valid-user    # and check auth info
  Order allow,deny
  Allow from x.y.z.t/24		# subnet with clients
  Allow @LOCAL
</Location>

If you don't want to use HTTPS when authentication is required, make sure you put the following line in cupds.conf, because the CUPS' default when compiled with SSL is to always use encryption when authentication is required:
```
DefaultEncryption ifrequested
```
The 'BasicDigest' line instructs CUPS to use passwd.md5 to check access credentials, while 'valid-user' prevents unknown users to access the service.
use the 'lppasswd' command to add username-password entries for the authorized clients. You can use the email address as a username, as it is convenient later to implement the email dispatch.
NOTE: lppasswd has a hardwired limit of 16 characters on the size of the username. To extend the field size you need to patch systemv/lppasswd.c to extend the field sizes (to 64 bytes in the example).

edit cups-pdf.conf adding the following lines:

#generate unique job-id for documents
Label 1
# path to the post-processing script
PostProcessing /usr/local/bin/cups-to-email
/cups/notifier/luigi-test-cups-pdf
#optionally create an entry for AnonUser to get better mail notifications
AnonUser cups-pdf

The change to AnonUser is only useful if you want a nice 'from' address in the email notification.

modify the source of cups-pdf.c to send the username to the script (otherwise, cups-pdf does not look at passwd.md5 and so will likely map all usernames to 'nobody'). The change is at patch-cups-pdf.c but it is not necessary for cups-pdf 2.4.7 or newer, as the patch has been integrated in the distribution;

create the 'cups-to-email' script e.g. as follows:

#!/bin/sh
FILE=$1
EMAIL=$3
DST="print-`jot -r 1 1000000 9999999`.pdf"	# random name
# copy the file in place and set permissions
cp $FILE ~cups-pdf/public_html/$DST
chmod 644 ~cups-pdf/public_html/$DST
# generate and send the email.
mail -s "Printed $DST" $EMAIL <<__EOF
File <a href=\"http://the.ser.ver/~cups-pdf/$DST\">
http://the.ser.ver/~cups-pdf/$DST</a>
__EOF