CUPS Implementation of IPP
Keywords: Programming, Internet Printing Protocol

#
CUPS Implementation of IPP

Last Updated May 20, 2025

## Introduction

CUPS implements the following Internet Printing Protocol standards:

- PWG 5100.1-2022: IPP Finishings v3.0 (FIN)
- PWG 5100.2-2001: "output-bin" Attribute Extension
- PWG 5100.3-2023: IPP Production Printing Extensions v2.0 (PPX)
- PWG 5100.5-2019: IPP Document Object v1.1
- PWG 5100.6-2003: IPP Page Overrides
- PWG 5100.7-2023: IPP Job Extensions v2.1 (JOBEXT)
- PWG 5100.8-2003: IPP "-actual" Attributes
- PWG 5100.9-2009: IPP Printer State Extensions
- PWG 5100.11-2024: IPP Enterprise Printing Extensions v2.0 (EPX)
- PWG 5100.12-2024: Internet Printing Protocol/2.x Fourth Edition
- PWG 5100.13-2023: IPP Driver Replacement Extensions v2.0 (NODRIVER)
- PWG 5100.14-2020: IPP Everywhere™ v1.1
- PWG 5100.16-2020: IPP Transaction-Based Printing Extensions v1.1
- PWG 5100.18-2025: IPP Shared Infrastructure Extensions v1.1 (INFRA)
- PWG 5100.22-2025: IPP System Service v1.1 (SYSTEM)
- PWG 5101.1-2023: PWG Media Standardized Names v2.1 (MSN)
- PWG 5102.4-2012: PWG Raster Format
- PWG 5107.3-2019: PWG MFD Alerts v1.1 (MFD Alerts)
- Registration: IPP Envelope Media Extensions v1.0 (ENVELOPE)
- Registration: IPP Label Printing Extensions v1.0
- Registration: IPP Privacy Attributes v1.0 (PRIVACY)
- Registration: IPP Wi-Fi Configuration Extensions v1.0 (WIFI)
- RFC 3380: IPP: Job and Printer Set Operations
- RFC 3510: IPP: IPP URL Scheme
- RFC 3995: IPP Event Notifications and Subscriptions
- RFC 3996: The 'ippget' Delivery Method for Event Notifications
- RFC 3998: IPP Job and Printer Administrative Operations
- RFC 7472: IPP over HTTPS Transport Binding and 'ipps' URI Scheme
- RFC 8010: IPP/1.1 Encoding and Transport
- RFC 8011: IPP/1.1 Model and Semantics

CUPS also defines many new operations and attributes to support multiple IPP printers and printer classes on a single host.

### IPP URIs

CUPS supports the "ipp" and "ipps" schemes. The following resource names are used:

`SCHEME://HOSTNAME:PORT/`
  Can be used for all "get" operations and for server subscriptions (deprecated).
`SCHEME://HOSTNAME:PORT/admin`
  Used for all administrative operations (deprecated).
`SCHEME://HOSTNAME:PORT/classes/PRINTER-NAME`
  Specifies a printer class (deprecated).
`SCHEME://HOSTNAME:PORT/ipp/print/PRINTER-NAME`
  Specifies a printer.
`SCHEME://HOSTNAME:PORT/ipp/print/PRINTER-NAME/JOB-ID`
  Specifies a job.
`SCHEME://HOSTNAME:PORT/ipp/system`
  Used for all system-wide operations.
`SCHEME://HOSTNAME:PORT/jobs/JOB-ID`
  Specifies a job (deprecated).
`SCHEME://HOSTNAME:PORT/printers/PRINTER-NAME`
  Specifies a printer (deprecated).

So a typical printer URI would be "ipp://foo.example.com/ipp/print/LaserJet".

### CUPS IPP Operations

CUPS has defined many vendor operations and extensions. The following operations are still in common use:

Operation Name | CUPS Version | Code | Brief Description
--- | --- | --- | ---
CUPS-Get-Printers | 1.0 | 0x4002 | Get all of the available printers.
CUPS-Create-Local-Printer | 2.2 | 0x4028 | Creates a local (temporary) print queue pointing to a remote IPP Everywhere printer.

## Operations

The following sections describe the operations supported by CUPS. In the interest of brevity, operations which use only the standard IPP attributes are not described.

### CUPS-Get-Printers Operation

The CUPS-Get-Printers operation (0x4002) returns the Printer attributes for every printer known to the system. This may include printers that are not served directly by the server.

#### CUPS-Get-Printers Request

The following groups of attributes are supplied as part of the CUPS-Get-Printers request:

Group 1: Operation Attributes

Natural Language and Character Set:
  The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1 of the IPP Model and Semantics document.
"limit" (integer (1:MAX)):
  The client OPTIONALLY supplies this attribute limiting the number of printers that are returned.
"printer-id" (integer(0:65535)):
  The client OPTIONALLY supplies this attribute to select which printer is returned.
"printer-location" (text(127)):
  The client OPTIONALLY supplies this attribute to select which printers are returned.
"printer-type" (type2 enum):
  The client OPTIONALLY supplies a printer type enumeration to select which printers are returned.
"printer-type-mask" (type2 enum):
  The client OPTIONALLY supplies a printer type mask enumeration to select which bits are used in the "printer-type" attribute.
"requested-attributes" (1setOf keyword):
  The client OPTIONALLY supplies a set of attribute names and/or attribute group names in whose values the requester is interested. If the client omits this attribute, the server responds as if this attribute had been supplied with a value of 'all'.
"requested-user-name" (name(127)):
  The client OPTIONALLY supplies a user name that is used to filter the returned printers.

#### CUPS-Get-Printers Response

The following groups of attributes are send as part of the CUPS-Get-Printers Response:

Group 1: Operation Attributes

Natural Language and Character Set:
  The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2 of the IPP Model and Semantics document.
Status Message:
  The standard response status message.

Group 2: Printer Object Attributes

The set of requested attributes and their current values for each printer.

### CUPS-Create-Local-Printer

The CUPS-Create-Local-Printer operation (0x4028) creates a local (temporary) print queue pointing to a remote IPP Everywhere Printer. The queue will remain until the scheduler idle exits, is restarted, or the system is restarted or shutdown. Temporary print queues can be made permanent by an administrator by setting the "printer-is-shared" attribute to 'true'.

At a minimum, the scheduler requires a name and URI for the Printer to add. When successful, the local "printer-uri" values are returned and may be used by the Client to submit Job Creation Requests, monitor for state changes, and so forth.

If the named printer already exists, the scheduler will reject the request with the 'client-error-not-possible' status code.

Access Rights: The authenticated user performing this operation MUST be a Local User of the system, and the request MUST be made over a local (domain socket or loopback interface) address. Otherwise, the request will be rejected with the 'client-error-forbidden' status code.

#### CUPS-Create-Local-Printer Request

The following group of attributes is supplied as part of the CUPS-Create-Local-Printer request:

Group 1: Operation Attributes

Natural Language and Character Set:
  The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1 of the IPP Model and Semantics document.

Group 2: Printer Attributes

"printer-name" (name(127)):
  The Client MUST supply this attribute which provides the name for the new Printer.
"device-uri" (uri):
  The Client MUST supply this attribute which provides an "ipp" or "ipps" URI pointing to an IPP Everywhere Printer.
"printer-device-id" (text(1023)):
  The Client OPTIONALLY supplies this attribute which provides the IEEE 1284 device ID for the new Printer.
"printer-geo-location" (uri):
  The Client OPTIONALLY supplies this attribute which provides the geo-location of the new Printer as a "geo" URI.
"printer-info" (text(127)):
  The Client OPTIONALLY supplies this attribute which provides the description for the new Printer.
"printer-location" (text(127)):
  The Client OPTIONALLY supplies this attribute which provides the location of the new Printer.

#### CUPS-Create-Local-Printer Response

The following group of attributes is sent as part of the CUPS-Create-Local-Printer Response:

Group 1: Operation Attributes

Natural Language and Character Set:
  The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2 of the IPP Model and Semantics document.
Status Message:
  The standard response status message.

Group 2: Printer Attributes

"printer-id" (integer(0:65535)):
  The numeric identifier for the created Printer.
"printer-is-accepting-jobs" (boolean):
  Whether the created Printer is accepting jobs at the time of the response.
"printer-state" (type1 enum):
  The state of the created Printer at the time of the response.
"printer-state-reasons" (1setOf type2 keyword):
  The state keywords for the created Printer at the time of the response.
"printer-uri-supported" (1setOf uri):
  The URIs for the created Printer.

## Attributes

CUPS provides many extension attributes to support multiple devices, PPD files, standard job filters, printers, and printer classes.

### Operation Attributes

#### printer-type (enum)

The "printer-type" attribute is used to choose printers or classes with the CUPS-Get-Printers and CUPS-Get-Classes operations.

#### printer-type-mask (enum)

The "printer-type-mask" attribute is used to choose printers or classes with the CUPS-Get-Printers and CUPS-Get-Classes operations. The bits are defined identically to the printer-type attribute and default to all 1's.

### Job Status Attributes

#### job-media-progress (integer(0:100))

The "job-media-progress" status attribute specifies the percentage of completion of the current page. It is only valid when the Job is in the processing state.

#### job-printer-state-message (text(MAX))

The "job-printer-state-message" status attribute provides the last known value of the "printer-state-message" attribute for the Printer that processed (or is processing) the Job.

#### job-printer-state-reasons (1setOf type2 keyword)

The "job-printer-state-reasons" status attribute provides the last known value of the "printer-state-reasons" attribute for the Printer that processed (or is processing) the Job.

#### page-border (type2 keyword)

The "page-border" attribute specifies whether a border is draw around each page. The following keywords are presently defined:

- 'double': Two hairline borders are drawn
- 'double-thick': Two 1pt borders are drawn
- 'none': No border is drawn (default)
- 'single': A single hairline border is drawn
- 'single-thick': A single 1pt border is drawn

### Job Template Attributes

#### job-cancel-after (integer(1:MAX))

The "job-cancel-after" attribute provides the maximum number of seconds that are allowed for processing a job.

#### Extensionjob-hold-until (keyword | name(MAX))

The "job-hold-until" attribute specifies a hold time. In addition to the standard IPP/1.1 keyword names, CUPS supports name values of the form "HH:MM" and "HH:MM:SS" that specify a hold time. The hold time is in Universal Coordinated Time (UTC) and not in the local time zone. If the specified time is less than the current time, the Job is held until the next day.

#### Extensionjob-sheets (1setof type2 keyword | name(MAX))

The "job-sheets" attribute specifies one or two banner files that are printed before and after a job. The reserved value of "none" disables banner printing. The default value is stored in the "job-sheets-default" attribute.

If only one value is supplied, the banner file is printed before the Job. If two values are supplied, the first value is used as the starting banner file and the second as the ending banner file.

#### job-originating-host-name (name(MAX))

The "job-originating-host-name" status attribute specifies the host from which the Job was queued. The value will be the hostname or IP address of the client depending on whether hostname resolution is enabled. The localhost address (127.0.0.1) is always resolved to the name "localhost".

This attribute is read-only.

### Printer Description Attributes

#### Deprecateddevice-uri (uri)

The "device-uri" attribute specifies the device URI of the Printer.

#### Deprecatedrequesting-user-name-allowed (1setof name(127))

The "requesting-user-name-allowed" attribute lists all of the users that are allowed to access a printer or class. Either this attribute or the "requesting-user-name-denied" attribute will be defined, but not both.

#### Deprecatedrequesting-user-name-denied (1setof name(127))

The "requesting-user-name-denied" attribute lists all of the users that are not allowed to access a printer or class. Either this attribute or the "requesting-user-name-allowed" attribute will be defined, but not both.

### Printer Status Attributes

CUPS and AirPrint define additional printer supply attributes that provide similar information to the IPP "printer-supply", "printer-supply-description", and "printer-supply-info-uri" attributes defined in the IPP Driver Replacement Extensions v2.0 (NODRIVER).

#### marker-change-time (integer)

The "marker-change-time" status attribute specifies the "printer-up-time" value when the last change to the marker-colors, marker-levels, marker-message, marker-names, or marker-types attributes was made.

#### marker-colors (1setof name(MAX))

The "marker-colors" status attribute specifies the color(s) for each supply in the Printer. The color is either 'none' or one or more hex-encoded sRGB colors of the form '#RRGGBB', for example '#000000' and '#00FFFF#FF00FF#FFFF00' for a printer with a black and CMY ink cartridge.

#### marker-high-levels (1setof integer(0:100))

The "marker-high-levels" status attribute specifies the supply levels that indicate a near-full condition. A value of 100 is used for supplies that are consumed/emptied such as ink and toner cartridges, and a value of 0 is used for supplies that are filled such as waste containers/recptacles.

#### marker-levels (1setof integer(-3:100))

The "marker-levels" status attribute specifies the current supply levels for the Printer. A value of -1 indicates the level is unavailable, -2 indicates unknown, and -3 indicates the level is unknown but has not yet reached capacity. Values from 0 to 100 indicate the corresponding percentage.

#### marker-low-levels (1setof integer(0:100))

The "marker-low-levels" status attribute specifies the supply levels that indicate a near-empty (for supplies that are consumed) or near-full (for supplies that are filled) condition. The low values for supplies like ink and toner are often in the range of 5 to 15 percent while waste containers/receptacles typically are in the range of 85 to 95.

#### marker-message (text(MAX))

The "marker-message" status attribute provides a human-readable status message for the current supply levels such as '12 pages of ink remaining.' or 'Replace cyan toner soon.'

#### marker-names (1setof name(MAX))

The "marker-names" status attribute specifies the name(s) for each supply in the Printer, for example 'Black Toner (TK10)' for a B&W laser printer.

#### marker-types (1setof keyword)

The "marker-types" status attribute specifies the type(s) of each supply in the Printer. The following (RFC 3805) types are currently supported:

- 'banding-supply'
- 'binding-supply'
- 'cleaner-unit'
- 'corona-wire'
- 'covers'
- 'developer'
- 'fuser-cleaning-pad'
- 'fuser-oil-wick'
- 'fuser-oil'
- 'fuser-oiler'
- 'fuser'
- 'ink-cartridge'
- 'ink-ribbon'
- 'ink'
- 'inserts'
- 'opc'
- 'paper-wrap'
- 'ribbon-wax'
- 'shrink-wrap'
- 'solid-wax'
- 'staples'
- 'stiching-wire'
- 'toner-cartridge'
- 'toner'
- 'transfer-unit'
- 'waste-ink'
- 'waste-toner'
- 'waste-water'
- 'waste-wax'
- 'water'

#### printer-type (enum)

The "printer-type" status attribute specifies printer type and capability bits for the Printer. The following bits are defined:

Bit | Description
--- | ---
0x00000001 | Is a printer class.
0x00000002 | Is a remote destination.
0x00000004 | Can print in black.
0x00000008 | Can print in color.
0x00000010 | Can print on both sides of the page in hardware.
0x00000020 | Can staple output.
0x00000040 | Can do fast copies in hardware.
0x00000080 | Can do fast copy collation in hardware.
0x00000100 | Can punch output.
0x00000200 | Can cover output.
0x00000400 | Can bind output.
0x00000800 | Can sort output.
0x00001000 | Can handle media up to US-Legal/A4.
0x00002000 | Can handle media from US-Legal/A4 to ISO-C/A2.
0x00004000 | Can handle media larger than ISO-C/A2.
0x00008000 | Can handle user-defined media sizes.
0x00010000 | Is an implicit (server-generated) class.
0x00020000 | Is the a default printer on the network.
0x00040000 | Is a facsimile device.
0x00080000 | Is rejecting jobs.
0x00100000 | Delete this queue.
0x00200000 | Queue is not shared.
0x00400000 | Queue requires authentication.
0x00800000 | Queue supports CUPS command files.
0x01000000 | Queue was automatically discovered and added.
0x02000000 | Queue is a scanner with no printing capabilities.
0x04000000 | Queue is a printer with scanning capabilities.