Appendix A Using the Internet Printing Protocol

This appendix includes information for using the Internet Printing Protocol (IPP) in the Oracle Solaris OS. IPP provides interoperability for CUPS and Windows clients. In the Oracle Solaris OS, the PAPI implementation of IPP provides both server-side and client-side printing support.

The following information is included in this appendix:

• Overview of Oracle Solaris IPP Support

• Overview of the IPP Listening Service

• IPP Components

• IPP Support Model

• IPP Server-Side Support

• IPP Client-Side Support

• IPP Attributes

• IPP Operation Keywords

For more information about open printing, go to http://sf.net/projects/openprinting.

Overview of Oracle Solaris IPP Support

IPP is an application level network printing protocol that can be used for distributed printing though the use of Internet tools and technologies. The protocol was initiated to provide universal solutions for printing documents from the Internet. IPP is employed by several system and printer vendors because the protocol includes tools that are necessary to make a broad set of standard requests and receive standard responses from print client systems. IPP provides versioning, extensibility, and security, as well as enhanced functionality, including improvements in job and printer status retrieval.

IPP support in the Oracle Solaris release is comprised of client-side support and server-side support. Both the client-side and the server-side support share some common elements, as well as elements that are unique to either client or server operations. IPP client and server support shares a base code that implements some of these common components. Server-side support for IPP is available, starting with the Solaris 10 3/05 release. Client-side support was introduced in the Solaris 10 5/08 release.

With IPP, you can perform the following tasks:

• Find out about a printer's capabilities

• Submit print jobs to a printer

• Determine the status of a printer or a print job

• Cancel a previously submitted print job

• Hold, release, and restart print jobs

• Modify print jobs

• Move print jobs between queues

• Accept, reject, enable, and disable print queues

• Modify and delete printers

IPP includes a simplified model for printing that abstracts the various facets of real world printing solutions. This model uses objects, attributes, and a set of operations that are performed against these objects. IPP uses these abstracts to communicate information between print service consumers, or customers, and print service providers in a detailed, standard, extensible, and secure manner.

Overview of the IPP Listening Service

The IPP Listening Service, also referred to as the listener, provides an IPP network protocol service that enables print client systems with a means of interacting with a print service on the system that is running the listener. This listener implements server-side IPP support, which includes a set of standard operations and attributes. The listener is implemented on Oracle Solaris as an Apache module and a series of shared libraries containing IPP operation and wire support. The IPP software stack is installed when the Oracle Solaris OS is installed on the system. The IPP listening service is an SMF service that depends on the print service to run. As a result, IPP is automatically enabled on a print server when the first print queue has been added . It is also disabled when the last print queue has been removed.

On the front end, IPP server support is layered on top of HTTP, Version 1.1. The server receives IPP operations through an HTTP POST request. The server then performs the requested operation and sends a response back to the client via HTTP. These operations include, but are not limited to, submitting and canceling a print job, and querying attributes of a printer, a print job, or all the print jobs that have been queued to a printer. On the back end, the IPP listener performs operations by communicating with a print spooler. In the Oracle Solaris OS, this spooler is currently the lpsched daemon.

How the IPP Listening Service Works

The IPP Listening Service implementation (server-side support) is embedded under the Apache web server. The web server receives IPP operations through HTTP POST requests. When an HTTP POST request is received, it is then passed on to the Apache IPP module (mod_ipp.so). Based on configuration, the Apache web service can also provide an authentication service and be used for encryption between print client and server. The listening service runs as it's own dedicated instance of Apache.

This process is as follows:

1. An IPP request is sent from the client to the server.

2. The Apache web server accepts the connection.

3. The Apache web server then hands the connection to mod_ipp.

4. mod_ipp passes the connection and configuration data to libipp-listener.

5. libipp-listener reads the request by using lipipp-core.

6. libipp-listener dispatches the request to the operation handler located in lipipp-listener.

7. The operation handler converts the request to a PAPI call and then makes the call.

8. The PAPI call is translated to a print service specific request by using psm-lpsched.

9. The print service responds to the request.

10. The psm-lpsched command converts the response to PAPI results.

11. The libpapi operation returns to the libipp-listener operation handler.

12. The libipp-listener operation handler passes results to dispatcher.

13. The libipp-listener dispatcher writes results to client by using the libipp-core library.

14. The dispatcher returns the mod_ipp entry point.

IPP Components

The following table describes the components that make up IPP support in the Oracle Solaris OS:

IPP Libraries

The IPP Listening Service library (libipp-listener) – Is where the bulk of the protocol request processing occurs. The library reads and validates requests by using the core IPP library, libipp-core.so. After the request has been validated, the request is translated to a series of client API calls. The result of these calls are then translated into an appropriate IPP response by using the core IPP library. The response is returned to the client system by the web server. The interface to the listening service library is a project private interface that is specific to the IPP server-side implementation.

The IPP Core library (libipp-core.so) – Is shared between client and server operation. The IPP core library contains routines that enable it to read and write protocol requests and responses. The library converts IPP request and response data between the standard binary representation and a set of common data structures. Ultimately, this common data representation is used in translating requests to and from a print service neutral representation and passed between a generic printing interface, libpapi.so. Since both client-side and server-side IPP support must perform this function, this is shared by clients and servers.

The PAPI library (libpapi.so) – Provides applications a print service independent means of interacting with a print service or protocol. In this instance, it provides the Apache IPP listening service a means of interacting with the local LP service. It determines the print service to interact with based on client-side queue configuration data stored in the printers.conf configuration database.

IPP Support Model

The sections that follow describe the various aspects of the IPP support model.

IPP Object Model

IPP contains two basic object types: Printer and Job. Each object type contains characteristics of a real printer or a real print job. Each object type is defined as a set of possible attributes that can be supported by that particular object type.

To enable all Printer and Job objects to be unambiguously referenced, they are all identified by a Uniform Resource Identifier (URI). The URI concept and implementation as an identifier is useful because it provides a means of uniquely identifying both the method of communicating with the print service (IPP) and a distinct network identifier for a printer queue (//server/printers/queue) or job.

When a print request is created, the IPP protocol message generated must contain the printer-uri of the Printer object the operation is to be performed against. Possible values for a printer-uri can be retrieved from a printer object or naming service printer-uri-supported attribute.

IPP Printer Object

The Printer object is the main object in the IPP model. The Printer object provides the server-side support for IPP. The Printer object contains the functions that are normally associated with physical output devices. These functions include spooling, scheduling, transformation, and managing of multiple devices that are associated with the print server. Printer objects are uniquely identified by a printer-uri. They can be registered as entries in a directory for the purpose of searching and locating static information about the Printer object, such as name, context, and printer capabilities. Dynamic information, for example, the number of jobs that are queued to the printer, errors and warnings, are associated with the Printer object itself.

A Printer object can be used to represent a real or virtual device, as long as the semantics are consistent with those of a Printer object.

IPP clients implement the protocol on the client-side, providing you, or a program running on your behalf, the ability to query Printer objects for the purpose of submitting and managing print jobs. The IPP server is the part of the Printer object that implements the application semantics of the print service. Printer objects can be embedded in an output device or they can be implemented on network host that communicates with an output device.

When a job is submitted to a Printer object, the Printer object validates the attributes in the request and then creates the Job object. When you query a job status or monitor its progress, you are interacting with the Job object. If you cancel a print job, you are using the Job objects's Cancel-job operation. For more information about Job object operations, see IPP Operation Keywords.

IPP Job Object

A Job object is used to model a print job. Job objects contain documents. The information that is required to create a Job object is sent to the print sever in the form of a create request when you initiate a print request through the IPP client to the Printer object. The Printer object validates the create request, and if accepted, the Printer object then creates a new Job object. This object is uniquely identified by a combination of printer-uri and job-id attributes or a job-uri attribute. See IPP Operation Keywords for more details.

IPP Server-Side Support

The IPP listening service provides an IPP network protocol service that enables print client systems a means of interacting with a print service on the system that is running the listener. This listener implements server-side IPP protocol support that includes a broad set of standard operations and attributes. The listener is implemented in the Oracle Solaris OS as an Apache module and a series of shared libraries that contain IPP operation and wire support. The IPP software stack is installed when the Oracle Solaris OS is installed on the system. The IPP listening service is an SMF service that depends on the print service to run. As a result, IPP is automatically enabled on a print server when the first print queue has been added . IPP is disabled when the last print queue has been removed.

Server-side support for IPP starts with the IPP module, mod_ipp. The listening service uses the Apache web server because the Oracle Solaris OS ships with Apache software. The Apache module uses the Dynamic Shared Object (DSO) interface to plug in under the web server. Using the DSO interface, the module includes configuration support for the IPP Listening service and an entry point for the web server to hand the listener the HTTP connection. This modular approach enables the IPP support to reuse Apache delivered encryption and authentication mechanisms.

Figure A–1 IPP Server Configuration

Configuration of IPP Server-Side Data

The IPP listening service configuration file, /etc/apache/httpd-standalone-ipp.conf, is like any normal Apache 1.3 configuration file. The configuration files takes any Apache 1.3 configuration directives that you want to use.

The default configuration includes the following features:

• Listening on port 631.

• Loading of a minimal set of Apache modules.

• Enabling all supported IPP operations at the /printers/path (ipp://server/printers/) without requiring authentication.

The default operations that are enabled for /printers/ is limited to a set of operations that poses less of a security risk. However, all operations are enabled at the /admin/path (ipp://server/admin/), with basic authentication required.

The mod_ipp Apache configuration options to choose from are described in the following table:

The following table shows the conformance checking types for the Apache Web Server Configuration. The syntax to use is:

ipp-conformance value

The following is an annotated example of an apache configuration file:

if mod_ipp is loaded User lp run as "lp"
URI: ipp://{host]/printers/{queue}
SetHandler application/ipp use mod_ipp for this location
ipp-conformance strict enable strict protocol checking (default)
ipp-operation all enable enable all supported operations

IPP Operation Keywords

IPP objects support operations. An operation consists of a request and a response. When a print client communicates with an IPP object, the client issues an operation request to the URI for that object. Operation requests and responses have parameters that identify the operation. Operations also have attributes that affect the run time characteristics of the operation. These operation-specific attributes are defined as operation attributes. Print requests contain operation attributes, object attributes, and the required document data to perform the specific operation. Each request requires a response from the object. Each response indicates success or failure of the operation with a corresponding status code as a response parameter. Responses contain operation attributes, object attributes, and status messages that are generated during the operation request.

The following table describes the IPP operation keywords for the Apache Web Server Configuration.

IPP Client-Side Support

The IPP client-side support in Oracle Solaris is implemented underneath the PAPI. This support enables any applications that are using the PAPI to use IPP, as well as other print services and protocols.

Applications include the following:

• GNOME Desktop Environment - Applications using libgnomeprint

• BSD commands - BSD UNIX LPD print service commands:

  • lpr

  • lpq

  • lprm

  • lpc

• LP commands - System V UNIX LP print service commands:

  • lp

  • lpstat

  • lpmove

  • accept

  • reject

  • enable

  • disable

The IPP client-side support for applications is provided through a loadable module, psm-ipp.so, that is loaded at runtime, based on the printer-uri for the printer or job that is being manipulated.

Because IPP is layered on top of an HTTP transport, both client-side and server-side support need the ability to read and write HTTP protocol. On the server-side, this support is provided by the Apache web server. On the client-side, this support is provided by an HTTP library, libhttp-core.so.

lpsched Support

psm-lpsched provides a translation between the print service independent representation of the PAPI and the LP print spooler (lpsched). It takes the PAPI attributes passed into various PAPI functions and converts them into an internal lpsched representation of the data. It then contacts lpsched to perform the requested operation. Once performed, it converts the results back into a print service neutral PAPI representation and returns them to the caller.

The LP print spooler (lpsched), provides a spooling service, translations of job data to a printer ready format, and transmission of the job data to the physical printer.

IPP Attributes

For each object instance, there is a set of supported attributes and values that describes a specific implementation of that object.

An object's attributes and values include the following information about that object:

• State

• Capabilities

• Features

• Job processing functions

• Default behaviors

• Default characteristics

Each attribute that defines an object is included in a set. This set of attributes for a specific object includes all of the attributes that the object could potentially support. For attributes that are labeled as REQUIRED, each object must support the attribute. If an attribute is labeled OPTIONAL, then each object may support the attribute.

Printer attributes are divided in to two groups:

job-template

These attributes describe the supported job processing capabilities and defaults for the Printer object.

printer-description

These attributes include identification, state, location, and references to other sources of information about the Printer object.

Examples of configurations that support a Printer object include the following:

• Output device with no spooling capabilities

• Output device with a built-in spooler

• Print server that supports IPP, with one or more associated output devices where the following applies:

  • Might or might not be capable of spooling jobs

  • Might or might not support IPP

The characteristics of a Job object are also described by its attributes.

Job attributes are grouped into two groups:

• job-template – These attributes are supplied by you or the print client. The attributes include job processing instructions that are intended to override any Printer object defaults or instructions that might be embedded within the document data.

• job-description – These attributes include the following information about the Job object:

  • Identification

  • State

  • Size

Note that the print client supplies some of these attributes, while the Printer object generates others. An implementation can support multiple documents per Job object, but it must support at least one document per Job object.

In IPP, Version 1.0 and Version 1.1, a document is not modeled as an IPP object. Therefore, the document has no object identifier or associated attributes. All job processing instruction are modeled as Job object attributes. These attributes are called Job Template attributes. These attributes apply equally to all documents within a Job object.

IPP objects have relationships that are maintain persistently along with the persistent storage of the object attributes.

For task related information, see Configuring the Internet Printing Protocol.