1. INTRODUCTION
---------------

AirPrint is an Apple technology that helps you create full-quality printed
output from iOS or OS X devices without the need to download or install
drivers.

Some printers support AirPrint natively; for those you don't need CUPS
AirPrint support. For any other printer, if it can be printed to via CUPS
on openSUSE, this package provides the additional tools and configuration
files needed to add CUPS AirPrint support for basic printing tasks from
iOS or OS X devices. For limitations see the "caveats" section below.

CUPS AirPrint support works by combining three open-source technologies:
  -mDNS/DNS-SD (a.k.a. Bonjour, or ZeroConf) for printer discovery, and
  -CUPS for receiving print jobs that are sent from iOS or OS X devices
   via the IPP protocol, and
  -cups-filters + Linux printer drivers for converting the printing data
   in a print job (PDF or URF) into the native data format of the
   particular printer device that finally produces the printout.

On openSUSE Linux, the standard mDNS implementation is called Avahi.

This package is about the first item:
  -discovery of CUPS printers on iOS or OS X devices via mDNS/DNS-SD

The CUPS AirPrint support that is provided by this package generates
and publishes appropriate DNS-SD records for CUPS printers
so that iOS and OS X devices can use them.


2. CAVEATS
----------

In general: CUPS + Linux printer drivers != AirPrint.

Sharing CUPS printers (i.e. sharing printers with Linux printer drivers)
via appropriate DNS-SD records so that iOS and OS X devices can use them
often works but may also fail in spectacular and frustrating ways, which
is the reason why there is no native AirPrint support in CUPS.

In general basic printing tasks from iOS or OS X devices should work
like printing emails or web pages to standard Letter or A4 media.

But as soon as one goes beyond basic printing tasks things may fall apart.
Some examples what may not work when using CUPS as an AirPrint server:
  -Ready media (that's how one gets to pick media sizes on iOS)
  -Proper media selection, scaling, and rotation
  -Printer status ("out of paper", etc.)
  -Duplex printing with some printers
  -Color/grayscale mode
  -Copies

Some of these deficiencies would require major changes to CUPS and its
driver architecture to fix, others require driver and (in some cases)
printer firmware updates to correct.

For reference see the "How to enable AirPrint in CUPS" mail thread
on the "CUPS user discussion list" <cups@cups.org> in October 2015,
in particular see
  http://cups.org/pipermail/cups/2015-October/027192.html
  http://cups.org/pipermail/cups/2015-October/027196.html
  http://cups.org/pipermail/cups/2015-October/027201.html


3. PREREQUISITES
----------------

All printers for which you want to add CUPS AirPrint support must first
be set up to accept print jobs via CUPS. Only shared CUPS printers will
be offered for access via AirPrint.

At least some iOS apps send the URF format when printing via AirPrint so that
the matching urftopdf filter that is provided in cups-filters >= 1.0.25 is
required to convert URF into PDF (PDF is the current standard printing data
format which can be further converted into the printer's native data format).
Because cups-filters cannot be reasonably well used with traditional
CUPS <= 1.5.4 also a modern CUPS >= 1.6 is in practice required.

In the following instructions it is assumed (and recommended) that the CUPS and
Avahi servers are running on the same host, and that the default configuration
of Avahi is used. It is also assumed that the (Apple) client devices and the
CUPS/Avahi host are on the same subnet (see 6.2).


4. AUTOMATIC CONFIGURATION
--------------------------

By installing this package, some setup steps are automatically taken care of:

  -All required depencies are installed automatically (if you use zypper).

  -Some extra MIME configuration files for CUPS are added:

        /usr/share/cups/mime/apple.types
        /usr/share/cups/mime/local.convs

  -A tool for generating mDNS service profiles for CUPS printers is installed:

        /usr/sbin/airprint-generate.py


5. MANUAL CONFIGURATION
-----------------------

The following manual configuration steps must be carried out after installing
this package:


5.1 CUPS configuration

A "ServerAlias" configuration entry must be added to /etc/cups/cupsd.conf. You
can do it by running the command

  cupsctl "ServerAlias=$HOST.local"

or by editing the file manually. The command is convenient, but has the
unfortunate side effect of completely reformatting the cupsd.conf file, as well
as removing all comments from it.

Next, enable printer sharing if it isn't enabled already:

  cupsctl --share-printers

Make sure each individual printer you wish to access via AirPrint is also
shared.

Finally, restart CUPS:

  systemctl restart cups


5.2 Avahi configuration

Generate Avahi service definitions for your CUPS printers:

  airprint-generate.py -v -d /etc/avahi/services/

With the -v option, the script prints some output about the printers it
generates profiles for. If you see no output at all, check the CUPS settings.

Make sure that the Avahi service is running.


5.3 Firewall

In general regarding firewall protection see
  https://en.opensuse.org/SDB:CUPS_and_SANE_Firewall_settings

If there is a firewall between the CUPS/Avahi host and your Apple devices, the
relevant service ports must be opened:

  -port 631 (ipp)
  -port 5353 (mdns)

If you are using SuSEfirewall2, you can run "yast firewall" to open the ports.
Under "Allowed Services" you need to allow the "Zeroconf/Bonjour Multicast DNS"
service, and, in the advanced settings, to open the "ipp" TCP port.

If you want to edit /etc/sysconfig/SuSEfirewall2 manually, you need to add
"ipp" and "avahi" to the following variables:

  FW_SERVICES_EXT_TCP="ipp"
  FW_CONFIGURATIONS_EXT="avahi"


6. REMARKS
----------

6.1 CUPS internal mDNS responder

With CUPS version 1.4 an internal mDNS responder was added for announcing
printers on the local network. Unfortunately, the printer records it sends are
not accepted for use with AirPrint. [1]

The workaround is to publish duplicate printer records specifically tailored
for AirPrint, which is what this package is for.


6.2 Local subnet only

These instructions only work if your Apple devices are on the same subnet as
the CUPS/Avahi server. It is possible to make AirPrint work across subnets, but
it takes some more effort (e.g., see [2]), and it is out of scope for this
package.

[1] http://www.finnie.org/2010/11/13/airprint-and-linux/
[2] http://pig.made-it.com/cups-dns-sd.html#7041


6.3 Trademarks

AirPrint, Bonjour, and OS X are trademarks of Apple Inc., registered
in the U.S. and other countries, see
  http://www.apple.com/legal/intellectual-property/trademark/appletmlist.html