cups-2.4.20

This README contains unresolved ports variables; replace them before using its commands.

+-----------------------------------------------------------------------
| Running cups on OpenBSD
+-----------------------------------------------------------------------

WARNING: CUPS lp commands are not compatible with the base system ones. When
using the CUPS command line, make sure to use the full path, e.g.
    /usr/local/bin/lpr
The same is true for manual pages, e.g.
    man -m /usr/local/man lpr

For a quick and easy (graphical) setup, after starting the CUPS daemon,
point your browser to:
    https://localhost:631

Alternatively, adding and/or configuring CUPS printers can be done with
lpadmin(8) (the foomatic tools may be needed as well, to create the
corresponding PPD file see below).

To be able to use CUPS printers from GTK+2 and GTK+3 applications, the
gtk+2-cups and gtk+3-cups packages need to be installed.

Printer drivers
===============
Printer drivers are available as separate packages. The Foomatic
framework provides most of them (see the foomatic-db-engine package
documentation for more information and creating PPD files;
${LOCALBASE}/share/doc/pkg-readmes/foomatic-db-engine).

Printer backends are also available as packages. Such list of packages can be
obtained using pkglocate(1) from the pkglocatedb package:
    $ pkglocate share/{cups/drv,ppd,foomatic/db/source}/ libexec/cups/backend/ |
	cut -d : -f 2 | sed -e s/,.*// | sort -u

Some PPD files are only available as part of vendor distributed Linux
driver packages (deb or rpm); if you're lucky, extracting the PPD file and
using it with CUPS on OpenBSD could work.

USB
===
Since USB printing will be handled by libusb, you need to allow
the _cups user access to the corresponding USB endpoint. To do so, find
where your printer is attached to using:
    $ usbdevs -v
then change the ownerships accordingly.

e.g.
Controller /dev/usb0:
<...>
addr 05: 03f0:4812 HP, Officejet 7500 E910
         high speed, self powered, config 1, rev 1.00, iSerialNumber MY2793100Q05JB
         driver: umass0
         driver: ugen1

# chown _cups /dev/ugen1.* /dev/usb0

For a multi-function device to work for both printing and scanning, the ugen(4)
and usb(4) devices must be accessible by the _cups user and the _saned group:
e.g.
    # chown _cups:_saned /dev/ugen1.* /dev/usb0 &&
	chmod 660 /dev/ugen1.* /dev/usb0

To preserve your changes after a system update, use rc.local(8).
Alternatively, hotplugd(8) attach/detach scripts can automate this.

*** WARNING ***
ulpt(4) needs to be disabled in the kernel (see bsd.re-config(5)) or the printer
will not be available to libusb:
# echo 'disable ulpt' >>/etc/bsd.re-config
# reboot

PARALLEL
========
To print to a parallel port attached printer, the CUPS daemon needs access to
the corresponding devices, e.g:
    chown _cups /dev/lp[a,t]0

This can be automated at boot time using rc.local(8).

Printer Sharing using mDNS
==========================
Browsing for shared printers can be done with multicast DNS (mDNS) using
the avahi daemon.

On the client side, "avahi-daemon" (from the avahi package) and
"cups-browsed" (from the cups-browsed package) must be running by
adding "avahi_daemon" and "cups_browsed" to pkg_scripts in rc.conf.local(8).
cups-browsed is a daemon that browses for network printers and automatically
create local queues pointing to them.

One the server side, "avahi-daemon" must be running by adding
"avahi_daemon" to pkg_scripts in rc.conf.local(8). Then
printer sharing can be activated using the CUPS web interface or running
the following commands as root or a member of the wheel group:
    cupsctl --share-printers
    lpadmin -p <printer_name> -o printer-is-shared=true

Printer Sharing across subnets using DNS-SD
===========================================
In general multicast DNS can only advertise shared printers on the local
subnet. This can be problematic if some clients are on a different
segment (e.g. wireless tablet devices).

Also some users may prefer to avoid the multicast traffic generated by
mDNS or prefer not to rely on avahi.

In such cases 'wide area' DNS service discovery (DNS-SD) can provide an
elegant solution. The administrator simply adds specially-formatted
static records to the DNS server used by the clients, that advertise the
address and capabilities of the print server. See http://www.dns-sd.org
for details.

DNS service discovery involves only the DNS records - there is no need
for the print server to run Avahi or for mDNS to be implemented. DNS-SD
and mDNS may however be used simultaneously if desired.

Sample extract from a DNS zone file:

	; zone file for the 'wlan' sub-domain of 'example.com.'
	;
	$ORIGIN wlan.example.com.
	$TTL 1h

	@       IN SOA  nameserver.example.com. admin.example.com. (
			1304061         ; zone file serial number
			3h              ; slave refresh 3 hours
			1h              ; slave retry 1 hour
			7d              ; slave expire 1 week
			1h              ; max caching time in case of failed lookups 1 hour
		)

	@       IN NS   nameserver.example.com.


	;=========================
	; DNS-SD resource records
	;=========================

	; DNS-SD domain enumeration
	; these records invite clients to browse this domain
	;
	b._dns-sd._udp  IN PTR @        ; b = browse domain (b._dns-sd._udp.wlan.example.com)
	lb._dns-sd._udp IN PTR @        ; lb = legacy browse domain (lb._dns-sd._udp.wlan.example.com)

	; DNS-SD named service entities
	; these records list the services we want clients to be able to discover
	;
	_cups._sub._ipp._tcp            IN PTR  Samsung\032Laser._printer._tcp
	_universal._sub._ipp._tcp       IN PTR  Samsung\032Laser._printer._tcp

	; DNS-SD srv and txt records
	; these describe each service entity listed above
	;
	Samsung\032Laser._printer._tcp  IN SRV 0 0 631 printserver.example.com.
					IN TXT (        "txtvers=1"
							"qtotal=1"
							"Transparent=T"
							"URF=DM3"
							"rp=printers/CLP-500"
							"note=Samsung colour laser"
							"product=(GPL Ghostscript)"
							"printer-state=3"
							"printer-type=0x82305c"
							"pdl=application/octet-stream,application/pdf,application/postscript,image/gif,image/jpeg,image/png,image/tiff,image/urf,text/html,text/plain,application/vnd.adobe-reader-postscript,application/vnd.cups-command,application/vnd.cups-pdf" )

	[... regular resource records ...]

Note: the fields and values encoded in the TXT record replicate those
that would appear in the mDNS announcement for the CUPS shared printer
- these can be determined for example with Tim Fontaine's
'airprint-generate' script. Using "URF=DM3" appears to provide the best
support for Apple iOS clients such as the iPad.