projects / thirdparty / cups.git / blame
| Commit | Line | Data |
|---|---|---|
| fce9ddcb MS |
1 | <!DOCTYPE html> |
| 2 | <html> | |
| 3 | <!-- SECTION: Getting Started --> | |
| 4 | <head> | |
| 5 | <title>Command-Line Printer Administration</title> | |
| 6 | <link rel="stylesheet" type="text/css" href="../cups-printable.css"> | |
| 7 | </head> | |
| 8 | <body> | |
| 9 | <h1 class="title">Command-Line Printer Administration</h1> | |
| 10 | ||
| f306ad4d | 11 | <p>This help document describes how to configure and manage destinations with CUPS.</p> |
| fce9ddcb | 12 | |
| fce9ddcb | 13 | |
| f306ad4d MS |
14 | <h2 class="title" id="INTRO">Introduction</h2> |
| 15 | ||
| 16 | <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> | |
| 17 | ||
| 18 | <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> | |
| 19 | ||
| f05177e2 | 20 | <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 <a href="man-cupsctl.html"><code>cupsctl(8)</code></a> program is used to manage the printing system as a whole, including things like <a href="#DEBUG">debug logging</a> and <a href="#SHARING">printer sharing</a>. 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> |
| f306ad4d MS |
21 | |
| 22 | ||
| 23 | <h2 class="title" id="PRINTERS">Managing Printers</h2> | |
| 24 | ||
| 25 | <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> | |
| 26 | ||
| 27 | <pre class="command">lpadmin -p printername ...</pre> | |
| 28 | ||
| 29 | <p>The <code>lpadmin</code> accepts several additional options after <code>-p printername</code> when adding or modifying a printer:</p> | |
| 30 | ||
| 31 | <dl> | |
| 32 | <dt><code>-D "description"</code></dt> | |
| 33 | <dd>Sets the description of the printer which is often shown instead of the printer name, for example "HP LaserJet".</dd> | |
| 34 | ||
| 35 | <dt><code>-E</code></dt> | |
| 36 | <dd>Enables the printer and accepts new print jobs.</dd> | |
| 37 | ||
| 38 | <dt><code>-L "location"</code></dt> | |
| 39 | <dd>Sets the location of the printer, for example "Conference Room".</dd> | |
| 40 | ||
| 41 | <dt><code>-m model</code></dt> | |
| 42 | <dd>Sets the printer driver using the <a href="#MODELS">model name</a>.</dd> | |
| 43 | ||
| 44 | <dt><code>-o option=value</code></dt> | |
| 45 | <dd>Sets the <a href="#OPTIONS">named option</a>.</dd> | |
| 46 | ||
| 47 | <dt><code>-v device-uri</code></dt> | |
| 48 | <dd>Sets the <a href="#DEVICES">URI for the printer</a>.</dd> | |
| 49 | ||
| 50 | </dl> | |
| 51 | ||
| f05177e2 | 52 | <p>The <code>-x</code> option deletes the named printer:</p> |
| f306ad4d MS |
53 | |
| 54 | <pre class="command">lpadmin -x printername</pre> | |
| fce9ddcb | 55 | |
| fce9ddcb | 56 | |
| f306ad4d MS |
57 | <h3 id="MODELS">Printer Drivers and PPDs</h3> |
| 58 | ||
| 59 | <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> | |
| fce9ddcb MS |
60 | |
| 61 | <pre class="command">lpinfo -m</pre> | |
| 62 | ||
| f306ad4d MS |
63 | <p>Each line contains the driver name followed by its description, for example:</p> |
| 64 | ||
| 65 | <pre class="example">drv:///sample.drv/dymo.ppd Dymo Label Printer | |
| 66 | drv:///sample.drv/epson9.ppd Epson 9-Pin Series | |
| 67 | drv:///sample.drv/epson24.ppd Epson 24-Pin Series | |
| 68 | drv:///sample.drv/generpcl.ppd Generic PCL Laser Printer | |
| 69 | drv:///sample.drv/generic.ppd Generic PostScript Printer | |
| 70 | drv:///sample.drv/deskjet.ppd HP DeskJet Series | |
| 71 | drv:///sample.drv/laserjet.ppd HP LaserJet Series PCL 4/5 | |
| 72 | drv:///sample.drv/intelbar.ppd Intellitech IntelliBar Label Printer, 2.1 | |
| 73 | drv:///sample.drv/okidata9.ppd Oki 9-Pin Series | |
| 74 | drv:///sample.drv/okidat24.ppd Oki 24-Pin Series | |
| 75 | drv:///sample.drv/zebracpl.ppd Zebra CPCL Label Printer | |
| 76 | drv:///sample.drv/zebraep1.ppd Zebra EPL1 Label Printer | |
| 77 | drv:///sample.drv/zebraep2.ppd Zebra EPL2 Label Printer | |
| 78 | drv:///sample.drv/zebra.ppd Zebra ZPL Label Printer | |
| 79 | everywhere IPP Everywhere</pre> | |
| 80 | ||
| 81 | <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> | |
| 82 | ||
| 83 | <pre class="command">lpadmin -p printername -E -v ipp://11.22.33.44/ipp/print -m everywhere</pre> | |
| 84 | ||
| 85 | <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> | |
| 86 | ||
| 87 | <pre class="command">lpadmin -p printername -E -v socket://11.22.33.44 -m drv:///sample.drv/laserjet.ppd</pre> | |
| 88 | ||
| 89 | <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> | |
| 90 | ||
| 91 | ||
| 92 | <h3 id="DEVICES">Device URIs (Backends)</h3> | |
| 93 | ||
| 94 | <p>CUPS comes with several standard backends that communicate with printers:</p> | |
| 95 | ||
| 96 | <ol> | |
| 97 | <li><code>dnssd</code>: The Bonjour (DNS-SD) protocol.</li> | |
| 98 | <li><code>ipp</code>: The Internet Printing Protocol (IPP) with optional encryption.</li> | |
| 99 | <li><code>ipps</code>: The Internet Printing Protocol with mandatory encryption.</li> | |
| 100 | <li><code>lpd</code>: The Line Printer Daemon protocol.</li> | |
| 101 | <li><code>socket</code>: The AppSocket (JetDirect) protocol.</li> | |
| 102 | <li><code>usb</code>: The Universal Serial Bus (USB) printer class.</li> | |
| 103 | </ol> | |
| 104 | ||
| 105 | <p>Run the <code>lpinfo -v</code> command to list the available backends and printers:</p> | |
| fce9ddcb MS |
106 | |
| 107 | <pre class="command">lpinfo -v</pre> | |
| 108 | ||
| f306ad4d MS |
109 | <p>Each line contains the backend "class" followed by the backend name or a full printer device URI, for example:</p> |
| 110 | ||
| 111 | <pre class="example">network lpd | |
| 112 | network ipps | |
| 113 | network ipp | |
| 114 | network socket | |
| 115 | network dnssd://Acme%20Laser%20Pro._ipp._tcp.local./?uuid=545253fb-1cb7-4d8d-98ed-ab6cd607cea7 | |
| 116 | network dnssd://Bar99._printer.tcp.local./?uuid=f9efff58-9086-4c95-accb-81dee876a475 | |
| 117 | network dnssd://Example%20EX-42._ipps._tcp.local./?uuid=4a0c67ad-2824-4ddf-9115-7d4226c5fe65 | |
| 118 | network dnssd://Foo%20Fighter-1969._pdl-datastream._tcp.local./?uuid=4e216bea-c3de-4f65-a710-c99e11c80d2b | |
| 119 | direct usb://ZP/LazerJet%20MFP?serial=42</pre> | |
| 120 | ||
| 121 | <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> | |
| 122 | ||
| 123 | <p>Once you know the correct URI for the printer, set it using the <code>lpadmin</code> command's <code>-v</code> option:</p> | |
| 124 | ||
| 125 | <pre class="command">lpadmin -p printername -v device-uri</pre> | |
| 126 | ||
| 127 | ||
| f05177e2 MS |
128 | <h3 id="OPTIONS">Printer Options</h3> |
| 129 | ||
| 130 | <p>The <code>lpadmin</code> command allows you to set various options for a printer:</p> | |
| 131 | ||
| 132 | <dl> | |
| 133 | <dt><code>-o cupsIPPSupplies=false</code></dt> | |
| 134 | <dd>Turns off IPP supply level reporting for a printer.</dd> | |
| 135 | ||
| 136 | <dt><code>-o cupsSNMPSupplies=false</code></dt> | |
| 137 | <dd>Turns off SNMP supply level reporting for a printer.</dd> | |
| 138 | ||
| 139 | <dt><code>-o name=value</code></dt> | |
| 140 | <dd>Sets the default value for the named PPD option. For example, <code>-o PageSize=Legal</code> sets the default page size to US Legal.</dd> | |
| 141 | ||
| 142 | <dt><code>-o printer-error-policy=name</code></dt> | |
| b167c7fc | 143 | <dd>Sets the policy for errors such as printers that cannot be found or accessed, don't support the format being printed, fail during submission of the print data, or cause one or more filters to crash:<dl> |
| f05177e2 MS |
144 | <dt><code>abort-job</code></dt> |
| 145 | <dd>Aborts the job on error.</dd> | |
| 146 | <dt><code>retry-job</code></dt> | |
| 147 | <dd>Retries the job at a future time.</dd> | |
| 148 | <dt><code>retry-current-job</code></dt> | |
| 149 | <dd>Retries the current job immediately.</dd> | |
| 150 | <dt><code>stop-printer</code></dt> | |
| 151 | <dd>Stops the printer on error.</dd> | |
| 152 | </dl></dd> | |
| 153 | ||
| 154 | <dt><code>-o printer-is-shared=true/false</code></dt> | |
| 155 | <dd>Enables/disables per-printer sharing. See the section on <a href="#SHARING">Printer Sharing</a> for more information.</dd> | |
| 156 | ||
| 157 | <dt><code>-o printer-op-policy=name</code></dt> | |
| 158 | <dd>Sets the operation policy associated with the printer. See the <a href="policies.html">Managing Operation Policies</a> help document for more information.</dd> | |
| 159 | ||
| 160 | <dt><code>-u allow:{user|@group}{,user|,@group}*</code></dt> | |
| 161 | <dt><code>-u allow:all</code></dt> | |
| 162 | <dt><code>-u deny:{user|@group}{,user|,@group}*</code></dt> | |
| 163 | <dt><code>-u deny:none</code></dt> | |
| 164 | <dd>Sets user-level access control for the printer. The <code>allow:</code> list defines a whitelist of users and groups while the <code>deny:</code> list defines a blacklist of users and groups.</dd> | |
| 165 | </dl> | |
| 166 | ||
| 167 | ||
| 168 | <h2 class="title" id="SHARING">Printer Sharing</h2> | |
| 169 | ||
| 170 | <p>CUPS supports sharing of printers with other computers and mobile devices. Two <code>cupsctl</code> options control the general printer sharing features:</p> | |
| 171 | ||
| 172 | <dl> | |
| 173 | <dt><code>--share-printers</code></dt> | |
| 174 | <dd>Enables sharing of printers with other computers and mobile devices on your local network.</dd> | |
| 175 | ||
| 176 | <dt><code>--remote-any</code></dt> | |
| 177 | <dd>Expands printer sharing to any network that can reach your server.</dd> | |
| 178 | </dl> | |
| 179 | ||
| 180 | <p>Once you have enabled printer sharing, you then must select which printers will be shared using the <code>lpadmin</code> command and the <code>-o printer-is-shared=true</code> option.</p> | |
| 181 | ||
| 182 | <p>For example, to share two printers ("foo" and "bar") on the local network, run the following commands:</p> | |
| 183 | ||
| 184 | <pre class="command">cupsctl --share-printers | |
| 185 | lpadmin -p foo -o printer-is-shared=true | |
| 186 | lpadmin -p bar -o printer-is-shared=true</pre> | |
| 187 | ||
| 188 | ||
| f306ad4d MS |
189 | <h2 class="title" id="CLASSES">Managing Classes</h2> |
| 190 | ||
| 191 | <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> | |
| fce9ddcb | 192 | |
| f306ad4d | 193 | <pre class="command">lpadmin -p printername -c classname</pre> |
| fce9ddcb | 194 | |
| f306ad4d | 195 | <p>The <code>-r</code> option specifies that the named printer is removed from the class:</p> |
| fce9ddcb | 196 | |
| f306ad4d | 197 | <pre class="command">lpadmin -p printername -r classname</pre> |
| fce9ddcb | 198 | |
| f05177e2 | 199 | <p>The <code>-x</code> option deletes the named class:</p> |
| fce9ddcb | 200 | |
| f306ad4d | 201 | <pre class="command">lpadmin -x classname</pre> |
| fce9ddcb | 202 | |
| f05177e2 MS |
203 | |
| 204 | <h2 class="title" id="DEBUG">Debug Logging and Troubleshooting</h2> | |
| 205 | ||
| 206 | <p>The <a href="man-cupsd-logs.html">printing system log files</a> track the activity of the scheduler, printer drivers, and backends. If problems occur and the log files do not provide sufficient details to diagnose the problem, you can enable debug logging using the <code>cupsctl</code> command:</p> | |
| 207 | ||
| 208 | <pre class="command">cupsctl --debug-logging</pre> | |
| 209 | ||
| 210 | <p>To disable debug logging, run the same command with the <code>--no-debug-logging</code> option:</p> | |
| 211 | ||
| 212 | <pre class="command">cupsctl --no-debug-logging</pre> | |
| fce9ddcb MS |
213 | </body> |
| 214 | </html> |