$OpenBSD: README-main,v 1.12 2014/07/12 13:41:47 ajacoutot Exp $

+-----------------------------------------------------------------------
| Running ${FULLPKGNAME} on OpenBSD
+-----------------------------------------------------------------------

Adding and/or configuring CUPS printers can be done with lpadmin(8), but
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).

Available 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-*).

To be able to use CUPS printers from GTK+3 applications, the gtk+3-cups
package needs to be installed.

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 `sudo usbdevs -vd` then change
the ownerships accordingly.

e.g.
Controller /dev/usb3:
addr 1: full speed, self powered, config 1, UHCI root hub(0x0000), Intel(0x8086), rev 1.00
  uhub3
 port 1 powered
 port 2 addr 2: full speed, self powered, config 1, USB MFP(0x082f), EPSON(0x04b8), rev 1.00, iSerialNumber L83010704250947490
   ugen0

$ sudo chown _cups /dev/ugen0.* /dev/usb3

The reason we are changing the user and not the group is that it will
allow for multi-function devices to work for both printing and scanning
(e.g. by being owned by _cups:_saned).

To preserve your changes after a system update, use rc.local(8).
e.g. for a multi-function printer/scanner add the following lines:
chown _cups:_saned /dev/ugen0.* /dev/usb1

Alternatively, hotplugd(8) attach/detach scripts can automate this.

*** WARNING ***
ulpt(4) needs to be disabled in the kernel (see config(8)) or the printer
will not be available to libusb.

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-filters package) must be running by
adding "avahi_daemon" and "cups_browsed" to pkg_scripts in rc.conf.local(8).

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.
