<body>
<h1 class="title">Command-Line Printer Administration</h1>
- <p>This help document describes how to configure and manage printers with CUPS.</p>
+ <p>This help document describes how to configure and manage destinations with CUPS.</p>
- <h2 class="title"><a name="INTRO">Introduction</a></h2>
- <p>CUPS currently uses PPD (PostScript Printer Description) files that describe printer capabilities and driver programs needed for each printer. The <code>everywhere</code> PPD is used for nearly all modern networks printers sold since about 2009. For example, the following command creates a print queue for a printer at address 11.22.33.44:
+ <h2 class="title" id="INTRO">Introduction</h2>
+
+ <p>Destinations are individual printers and classes (pools) of printers. <a href="#PRINTERS">Printers</a> use a description file with one or more driver ("filter") programs that communicate with the printer through a "backend" program. CUPS currently uses PPD (PostScript Printer Description) files to describe the printer and driver programs needed, some of which come with CUPS while others come with your operating system or Linux distribution. Backends are specified using a URI (Universal Resource Identifier) where the URI scheme is the backend name, e.g., "ipp://11.22.33.44/ipp/print" specifies the "ipp" backend - like PPD files, some backends come with CUPS while others come with your operating system.</p>
+
+ <p><a href="#CLASSES">Classes</a> are associated with one or more printers and are typically used to distribute print jobs amongst a group of printers or provide redundancy or high availability when printing. Print jobs sent to a class are forwarded to the next available printer in the class.</p>
+
+ <p>The <a href="man-lpadmin.html"><code>lpadmin(8)</code></a> program is used to add, modify, or delete destinations, while the <a href="man-lpinfo.html"><code>lpinfo(8)</code></a> command is used to list the available printer drivers and backends. The CUPS web interface ("http://localhost:631" or "https://servername:631") can also be used, and most operating systems provide their own GUI administration tools.</p>
+
+
+ <h2 class="title" id="PRINTERS">Managing Printers</h2>
+
+ <p>The <code>lpadmin</code> command is used to create, modify, or delete a printer. The <code>-p</code> option specifies a printer to create or modify:</p>
+
+ <pre class="command">lpadmin -p printername ...</pre>
+
+ <p>The <code>lpadmin</code> accepts several additional options after <code>-p printername</code> when adding or modifying a printer:</p>
+
+ <dl>
+ <dt><code>-D "description"</code></dt>
+ <dd>Sets the description of the printer which is often shown instead of the printer name, for example "HP LaserJet".</dd>
+
+ <dt><code>-E</code></dt>
+ <dd>Enables the printer and accepts new print jobs.</dd>
+
+ <dt><code>-L "location"</code></dt>
+ <dd>Sets the location of the printer, for example "Conference Room".</dd>
+
+ <dt><code>-m model</code></dt>
+ <dd>Sets the printer driver using the <a href="#MODELS">model name</a>.</dd>
+
+ <dt><code>-o option=value</code></dt>
+ <dd>Sets the <a href="#OPTIONS">named option</a>.</dd>
+
+ <dt><code>-v device-uri</code></dt>
+ <dd>Sets the <a href="#DEVICES">URI for the printer</a>.</dd>
+
+ </dl>
+
+ <p>The <code>-x<code> option deletes the named printer:</p>
+
+ <pre class="command">lpadmin -x printername</pre>
- <pre class="command">lpadmin -p printername -E -v ipp://11.22.33.44/ipp/print -m everywhere</pre>
- <p>CUPS also includes several sample PPD files you can use for "legacy" printers:</p>
-
- <div class="table"><table>
- <thead>
- <tr><th>Driver</th><th>PPD Name</th></tr>
- </thead>
- <tbody>
- <tr><td>Dymo Label Printers</td><td>drv:///sample.drv/dymo.ppd</td></tr>
- <tr><td>Intellitech Intellibar</td><td>drv:///sample.drv/intelbar.ppd</td></tr>
- <tr><td>EPSON 9-pin Series</td><td>drv:///sample.drv/epson9.ppd</td></tr>
- <tr><td>EPSON 24-pin Series</td><td>drv:///sample.drv/epson24.ppd</td></tr>
- <tr><td>Generic PCL Laser Printer</td><td>drv:///sample.drv/generpcl.ppd</td></tr>
- <tr><td>Generic PostScript Printer</td><td>drv:///sample.drv/generic.ppd</td></tr>
- <tr><td>HP DeskJet Series</td><td>drv:///sample.drv/deskjet.ppd</td></tr>
- <tr><td>HP LaserJet Series</td><td>drv:///sample.drv/laserjet.ppd</td></tr>
- <tr><td>OKIDATA 9-Pin Series</td><td>drv:///sample.drv/okidata9.ppd</td></tr>
- <tr><td>OKIDATA 24-Pin Series</td><td>drv:///sample.drv/okidat24.ppd</td></tr>
- <tr><td>Zebra CPCL Label Printer</td><td>drv:///sample.drv/zebracpl.ppd</td></tr>
- <tr><td>Zebra EPL1 Label Printer</td><td>drv:///sample.drv/zebraep1.ppd</td></tr>
- <tr><td>Zebra EPL2 Label Printer</td><td>drv:///sample.drv/zebraep2.ppd</td></tr>
- <tr><td>Zebra ZPL Label Printer</td><td>drv:///sample.drv/zebra.ppd</td></tr>
- </tbody>
- </table></div>
-
- <p>You can run the <code>lpinfo -m</code> command to list all of the available drivers:</p>
+ <h3 id="MODELS">Printer Drivers and PPDs</h3>
+
+ <p>The <code>-m</code> option to <code>lpadmin</code> specifies the driver ("model") to use for the printer. You can run the <code>lpinfo -m</code> command to list all of the available drivers ("models") on your system:</p>
<pre class="command">lpinfo -m</pre>
- <p>Run the <code>lpinfo -v</code> command to list the available printers:</p>
+ <p>Each line contains the driver name followed by its description, for example:</p>
+
+ <pre class="example">drv:///sample.drv/dymo.ppd Dymo Label Printer
+drv:///sample.drv/epson9.ppd Epson 9-Pin Series
+drv:///sample.drv/epson24.ppd Epson 24-Pin Series
+drv:///sample.drv/generpcl.ppd Generic PCL Laser Printer
+drv:///sample.drv/generic.ppd Generic PostScript Printer
+drv:///sample.drv/deskjet.ppd HP DeskJet Series
+drv:///sample.drv/laserjet.ppd HP LaserJet Series PCL 4/5
+drv:///sample.drv/intelbar.ppd Intellitech IntelliBar Label Printer, 2.1
+drv:///sample.drv/okidata9.ppd Oki 9-Pin Series
+drv:///sample.drv/okidat24.ppd Oki 24-Pin Series
+drv:///sample.drv/zebracpl.ppd Zebra CPCL Label Printer
+drv:///sample.drv/zebraep1.ppd Zebra EPL1 Label Printer
+drv:///sample.drv/zebraep2.ppd Zebra EPL2 Label Printer
+drv:///sample.drv/zebra.ppd Zebra ZPL Label Printer
+everywhere IPP Everywhere</pre>
+
+ <p>The <code>everywhere</code> driver is used for nearly all modern networks printers sold since about 2009. For example, the following command creates a destination for a printer at IP address 11.22.33.44:</p>
+
+ <pre class="command">lpadmin -p printername -E -v ipp://11.22.33.44/ipp/print -m everywhere</pre>
+
+ <p>The CUPS sample drivers (the "drv:///sample.drv/..." lines above) can be used for "legacy" printers. For example, the following command creates a destination for a HP LaserJet printer at IP address 11.22.33.44:</p>
+
+ <pre class="command">lpadmin -p printername -E -v socket://11.22.33.44 -m drv:///sample.drv/laserjet.ppd</pre>
+
+ <blockquote>Note: The CUPS sample drivers are designed to provide basic printing capabilities for the broadest range of printers possible, but generally do not exercise the full potential of the printers or CUPS. Other drivers (including the <code>everywhere</code> driver) provide greater printing capabilities and better print quality.</blockquote>
+
+
+ <h3 id="DEVICES">Device URIs (Backends)</h3>
+
+ <p>CUPS comes with several standard backends that communicate with printers:</p>
+
+ <ol>
+ <li><code>dnssd</code>: The Bonjour (DNS-SD) protocol.</li>
+ <li><code>ipp</code>: The Internet Printing Protocol (IPP) with optional encryption.</li>
+ <li><code>ipps</code>: The Internet Printing Protocol with mandatory encryption.</li>
+ <li><code>lpd</code>: The Line Printer Daemon protocol.</li>
+ <li><code>socket</code>: The AppSocket (JetDirect) protocol.</li>
+ <li><code>usb</code>: The Universal Serial Bus (USB) printer class.</li>
+ </ol>
+
+ <p>Run the <code>lpinfo -v</code> command to list the available backends and printers:</p>
<pre class="command">lpinfo -v</pre>
- <p>Then use the correct URI to add the printer using the <code>lpadmin</code> command:</p>
+ <p>Each line contains the backend "class" followed by the backend name or a full printer device URI, for example:</p>
+
+ <pre class="example">network lpd
+network ipps
+network ipp
+network socket
+network dnssd://Acme%20Laser%20Pro._ipp._tcp.local./?uuid=545253fb-1cb7-4d8d-98ed-ab6cd607cea7
+network dnssd://Bar99._printer.tcp.local./?uuid=f9efff58-9086-4c95-accb-81dee876a475
+network dnssd://Example%20EX-42._ipps._tcp.local./?uuid=4a0c67ad-2824-4ddf-9115-7d4226c5fe65
+network dnssd://Foo%20Fighter-1969._pdl-datastream._tcp.local./?uuid=4e216bea-c3de-4f65-a710-c99e11c80d2b
+direct usb://ZP/LazerJet%20MFP?serial=42</pre>
+
+ <p>The <code>network</code> class of backends is used for all network protocols. The <a href="network.html">Using Network Printers</a> help document describes how to use the standard CUPS network backends. The <code>direct</code> class of backends is used for directly-connected printers such as USB and Bluetooth. Because these backends use a system-specific identifier, you should only use the reported device URIs.</p>
+
+ <p>Once you know the correct URI for the printer, set it using the <code>lpadmin</code> command's <code>-v</code> option:</p>
+
+ <pre class="command">lpadmin -p printername -v device-uri</pre>
+
+
+ <h2 class="title" id="CLASSES">Managing Classes</h2>
+
+ <p>The <code>lpadmin</code> command is used to create, modify, or delete a class. The <code>-c</code> option specifies a class to create or modify and is combined with the <code>-p</code> option:</p>
- <pre class="command">lpadmin -p printername -E -v device-uri -m ppd-name</pre>
+ <pre class="command">lpadmin -p printername -c classname</pre>
- <p>Current network printers typically use <code>ipp</code> or <code>ipps</code> URIS:</p>
+ <p>The <code>-r</code> option specifies that the named printer is removed from the class:</p>
- <pre class="command">lpadmin -p printername -E -v ipp://11.22.33.44/ipp/print -m everywhere
-lpadmin -p printername -E -v ipps://11.22.33.44/ipp/print -m everywhere</pre>
+ <pre class="command">lpadmin -p printername -r classname</pre>
- <p>Older network printers typically use <code>socket</code> or <code>lpd</code> URIs:</p>
+ <p>The <code>-x<code> option deletes the named class:</p>
- <pre class="command">lpadmin -p printername -E -v socket://11.22.33.44 -m ppd-name
-lpadmin -p printername -E -v lpd://11.22.33.44/ -m ppd-name</pre>
+ <pre class="command">lpadmin -x classname</pre>
- <p>The sample drivers provide basic printing capabilities, but generally do not exercise the full potential of the printers or CUPS. Other drivers provide greater printing capabilities.</p>
</body>
</html>
static int delete_printer_option(http_t *http, char *printer,
char *option);
static int enable_printer(http_t *http, char *printer);
-static char *get_printer_ppd(const char *uri, char *buffer, size_t bufsize);
+static char *get_printer_ppd(const char *uri, char *buffer, size_t bufsize, int *num_options, cups_option_t **options);
static cups_ptype_t get_printer_type(http_t *http, char *printer, char *uri,
size_t urisize);
static int set_printer_options(http_t *http, char *printer,
if ((ppd_name = cupsGetOption("ppd-name", num_options, options)) != NULL && !strcmp(ppd_name, "everywhere") && (device_uri = cupsGetOption("device-uri", num_options, options)) != NULL)
{
- if ((file = get_printer_ppd(device_uri, evefile, sizeof(evefile))) == NULL)
+ if ((file = get_printer_ppd(device_uri, evefile, sizeof(evefile), &num_options, &options)) == NULL)
return (1);
num_options = cupsRemoveOption("ppd-name", num_options, &options);
* 'get_printer_ppd()' - Get an IPP Everywhere PPD file for the given URI.
*/
-static char * /* O - Filename or NULL */
-get_printer_ppd(const char *uri, /* I - Printer URI */
- char *buffer, /* I - Filename buffer */
- size_t bufsize) /* I - Size of filename buffer */
+static char * /* O - Filename or NULL */
+get_printer_ppd(
+ const char *uri, /* I - Printer URI */
+ char *buffer, /* I - Filename buffer */
+ size_t bufsize, /* I - Size of filename buffer */
+ int *num_options, /* IO - Number of options */
+ cups_option_t **options) /* IO - Options */
{
http_t *http; /* Connection to printer */
ipp_t *request, /* Get-Printer-Attributes request */
*response; /* Get-Printer-Attributes response */
+ ipp_attribute_t *attr; /* Attribute from response */
char resolved[1024], /* Resolved URI */
scheme[32], /* URI scheme */
userpass[256], /* Username:password */
host[256], /* Hostname */
resource[256]; /* Resource path */
int port; /* Port number */
+ static const char * const pattrs[] = /* Attributes to use */
+ {
+ "job-template",
+ "printer-defaults",
+ "printer-description",
+ "media-col-database"
+ };
/*
request = ippNewRequest(IPP_OP_GET_PRINTER_ATTRIBUTES);
ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", NULL, uri);
+ ippAddStrings(request, IPP_TAG_OPERATION, IPP_TAG_KEYWORD, "requested-attributes", sizeof(pattrs) / sizeof(pattrs[0]), NULL, pattrs);
response = cupsDoRequest(http, request, resource);
- if (!_ppdCreateFromIPP(buffer, bufsize, response))
+ if (_ppdCreateFromIPP(buffer, bufsize, response))
+ {
+ if (!cupsGetOption("printer-geo-location", *num_options, *options) && (attr = ippFindAttribute(response, "printer-geo-location", IPP_TAG_URI)) != NULL)
+ *num_options = cupsAddOption("printer-geo-location", ippGetString(attr, 0, NULL), *num_options, options);
+
+ if (!cupsGetOption("printer-info", *num_options, *options) && (attr = ippFindAttribute(response, "printer-info", IPP_TAG_TEXT)) != NULL)
+ *num_options = cupsAddOption("printer-info", ippGetString(attr, 0, NULL), *num_options, options);
+
+ if (!cupsGetOption("printer-location", *num_options, *options) && (attr = ippFindAttribute(response, "printer-location", IPP_TAG_TEXT)) != NULL)
+ *num_options = cupsAddOption("printer-location", ippGetString(attr, 0, NULL), *num_options, options);
+ }
+ else
_cupsLangPrintf(stderr, _("%s: Unable to create PPD file: %s"), "lpadmin", strerror(errno));
ippDelete(response);
projects / thirdparty / cups.git / commitdiff
