doc/help/man-ipptool.html

   1 <!DOCTYPE html>
   2 <html>
   3   <head>
   4     <meta name="creator" content="mantohtml v2.0.2">
   5     <title>ipptool(1)</title>
   6   </head>
   7   <body>
   8     <h1 id="ipptool-1">ipptool(1)</h1>
   9     <h2 id="ipptool-1.name">Name</h2>
  10 <p>ipptool - perform internet printing protocol requests
  11 </p>
  12     <h2 id="ipptool-1.synopsis">Synopsis</h2>
  13 <p><strong>ipptool</strong>
  14 [
  15 <strong>--help</strong>
  16 ] [
  17 <strong>--bearer-token</strong>
  18 <em>BEARER-TOKEN</em>
  19 ] [
  20 <strong>--client-name</strong>
  21 <em>CLIENT-NAME</em>
  22 ] [
  23 <strong>--ippfile</strong>
  24 <em>FILENAME</em>
  25 ] [
  26 <strong>--stop-after-include-error</strong>
  27 ] [
  28 <strong>--version</strong>
  29 ] [
  30 <strong>-4</strong>
  31 ] [
  32 <strong>-6</strong>
  33 ] [
  34 <strong>-c</strong>
  35 ] [
  36 <strong>-C</strong>
  37 ] [
  38 <strong>-d</strong>
  39 <em>NAME=VALUE</em>
  40 ] [
  41 <strong>-E</strong>
  42 ] [
  43 <strong>-f</strong>
  44 <em>FILENAME</em>
  45 ] [
  46 <strong>-h</strong>
  47 ] [
  48 <strong>-i</strong>
  49 <em>SECONDS</em>
  50 ] [
  51 <strong>-I</strong>
  52 ] [
  53 <strong>-j</strong>
  54 ] [
  55 <strong>-L</strong>
  56 ] [
  57 <strong>-n</strong>
  58 <em>REPEAT-COUNT</em>
  59 ] [
  60 <strong>-P</strong>
  61 <em>FILENAME.plist</em>
  62 ] [
  63 <strong>-q</strong>
  64 ] [
  65 <strong>-R</strong>
  66 ] [
  67 <strong>-S</strong>
  68 ] [
  69 <strong>-t</strong>
  70 ] [
  71 <strong>-T</strong>
  72 <em>SECONDS</em>
  73 ] [
  74 <strong>-v</strong>
  75 ] [
  76 <strong>-V</strong>
  77 <em>VERSION</em>
  78 ] [
  79 <strong>-X</strong>
  80 ]
  81 <em>PRINTER-URI</em>
  82 <em>TESTFILE</em>
  83 [ ...
  84 <em>TESTFILE</em>
  85 ]
  86 </p>
  87     <h2 id="ipptool-1.description">Description</h2>
  88 <p><strong>ipptool</strong>
  89 sends IPP requests to the specified
  90 <em>printer-uri</em>
  91 and tests and/or displays the results.
  92 Each named
  93 <em>testfile</em>
  94 defines one or more requests, including the expected response status, attributes, and values.
  95 Output is either a plain text, formatted text, CSV, JSON, or XML report on the standard output, with a non-zero exit status indicating that one or more tests have failed.
  96 The
  97 <em>testfile</em>
  98 format is described in
  99 <a href="ipptoolfile.html"><strong>ipptoolfile</strong>(5).</a>
 100
 101 </p>
 102     <h2 id="ipptool-1.options">Options</h2>
 103 <p>The following options are recognized by
 104 <strong>ipptool:</strong>
 105 </p>
 106     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>--bearer-token </strong><em>BEARER-TOKEN</em><br>
 107 Specifies the OAuth 2.0 token to use for HTTP Bearer authentication (RFC 6750).
 108 </p>
 109     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>--client-name </strong><em>CLIENT-NAME</em><br>
 110 Specifies the client name to use for the TLS client certificate.
 111 If not specified, no client certificate is used during negotiation.
 112 </p>
 113     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>--help</strong><br>
 114 Shows program help.
 115 </p>
 116     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>--ippfile </strong><em>FILENAME</em><br>
 117 Specifies that the test results should be written to the named IPP file.
 118 These files can be used with programs like
 119 <a href="ippeveprinter.html"><strong>ippeveprinter</strong>(1).</a>
 120
 121 </p>
 122     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>--stop-after-include-error</strong><br>
 123 Tells
 124 <strong>ipptool</strong>
 125 to stop if an error occurs in an included file. Normally
 126 <strong>ipptool</strong>
 127 will continue with subsequent tests after the INCLUDE directive.
 128 </p>
 129     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>--version</strong><br>
 130 Shows the version of
 131 <strong>ipptool</strong>
 132 being used.
 133 </p>
 134     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-4</strong><br>
 135 Specifies that
 136 <strong>ipptool</strong>
 137 must connect to the printer or server using IPv4.
 138 </p>
 139     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-6</strong><br>
 140 Specifies that
 141 <strong>ipptool</strong>
 142 must connect to the printer or server using IPv6.
 143 </p>
 144     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-c</strong><br>
 145 Specifies that CSV (comma-separated values) output is desired instead of the plain text output.
 146 </p>
 147     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-C</strong><br>
 148 Specifies that requests should be sent using the HTTP/1.1 &quot;Transfer-Encoding: chunked&quot; header, which is required for conformance by all versions of IPP.
 149 The default is to use &quot;Transfer-Encoding: chunked&quot; for requests with attached files and &quot;Content-Length:&quot; for requests without attached files.
 150 </p>
 151     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-d</strong><em> NAME=VALUE</em>
 152 <br>
 153 Defines the named variable.
 154 </p>
 155     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-E</strong><br>
 156 Forces TLS encryption when connecting to the server using the HTTP &quot;Upgrade&quot; header.
 157 </p>
 158     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-f</strong><em> FILENAME</em>
 159 <br>
 160 Defines the default request filename for tests.
 161 </p>
 162     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-h</strong><br>
 163 Validate HTTP response headers.
 164 </p>
 165     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-i</strong><em> SECONDS</em>
 166 <br>
 167 Specifies that the (last)
 168 <em>testfile</em>
 169 should be repeated at the specified interval.
 170 This option is incompatible with the <strong>--ippfile</strong> (IPP file output) and <em>-P</em> or <strong>-X</strong> (XML plist output) options.
 171 </p>
 172     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-I</strong><br>
 173 Specifies that
 174 <strong>ipptool</strong>
 175 will continue past errors.
 176 </p>
 177     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-j</strong><br>
 178 Specifies that
 179 <strong>ipptool</strong>
 180 will produce JSON output.
 181 </p>
 182     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-l</strong><br>
 183 Specifies that plain text output is desired.
 184 </p>
 185     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-L</strong><br>
 186 Specifies that requests should be sent using the HTTP/1.0 &quot;Content-Length:&quot; header, which is required for conformance by all versions of IPP.
 187 The default is to use &quot;Transfer-Encoding: chunked&quot; for requests with attached files and &quot;Content-Length:&quot; for requests without attached files.
 188 </p>
 189     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-n</strong><em> REPEAT-COUNT</em>
 190 <br>
 191 Specifies that the (last)
 192 <em>testfile</em>
 193 should be repeated the specified number of times.
 194 This option is incompatible with the <em>--ippfile</em> (IPP file output) and <em>-P</em> or <em>-X</em> (XML plist output) options.
 195 </p>
 196     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-P</strong><em> FILENAME.plist</em>
 197 <br>
 198 Specifies that the test results should be written to the named XML (Apple plist) file in addition to the regular test report (<strong>-t</strong>).
 199 This option is incompatible with the <strong>-i</strong> (interval) and <strong>-n</strong> (repeat-count) options.
 200 </p>
 201     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-q</strong><br>
 202 Be quiet and produce no output.
 203 </p>
 204     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-S</strong><br>
 205 Forces (dedicated) TLS encryption when connecting to the server.
 206 </p>
 207     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-t</strong><br>
 208 Specifies that CUPS test report output is desired instead of the plain text output.
 209 </p>
 210     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-T</strong><em> SECONDS</em>
 211 <br>
 212 Specifies a timeout for IPP requests in SECONDS.
 213 </p>
 214     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-v</strong><br>
 215 Specifies that all request and response attributes should be output in CUPS test mode (<strong>-t</strong>).
 216 This is the default for CSV, JSON, and XML output.
 217 </p>
 218     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-V</strong><em> VERSION</em>
 219 <br>
 220 Specifies the default IPP version to use: 1.0, 1.1, 2.0, 2.1, or 2.2. If not specified, version 1.1 is used.
 221 </p>
 222     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-X</strong><br>
 223 Specifies that XML (Apple plist) output is desired instead of the plain text report.
 224 This option is incompatible with the <strong>-i</strong> (interval) and <strong>-n</strong> (repeat-count) options.
 225 </p>
 226     <h2 id="ipptool-1.exit-status">Exit Status</h2>
 227 <p>The
 228 <strong>ipptool</strong>
 229 program returns 0 if all tests were successful and 1 otherwise.
 230 </p>
 231     <h2 id="ipptool-1.files">Files</h2>
 232 <p>The following standard test files are available:
 233 </p>
 234     <pre>
 235     cancel-current-job.test           - Cancel the current job
 236     create-job.test                   - Create a job and send a document
 237     create-job-sheets.test            - &quot;&quot; with banner
 238     create-job-timeout.test           - &quot;&quot; with timeout
 239     create-printer-subscription.test  - Create a printer subscription
 240     cups-create-local-printer.test    - Create a local print queue
 241     fax-job.test                      - Fax a file (for fax queues)
 242     get-completed-jobs.test           - Get a list of completed jobs
 243     get-job-attributes.test           - Get attributes for a job
 244     get-job-template-attributes.test  - Get job ticket attributes for a printer
 245     get-jobs.test                     - Get a list of not-completed jobs
 246     get-notifications.test            - Get notifications for a subscription
 247     get-printer-attributes.test       - Get attributes for a printer
 248     get-printer-attributes-suite.test - Test Get-Printer-Attributes conformance
 249     get-printers.test                 - Get a list of printers
 250     get-subscriptions.test            - Get a list of subscriptions
 251     identify-printer.test             - Identify a printer
 252     identify-printer-display.test     - Identify a printer via the display
 253     ipp-1.1.test                      - Run IPP/1.1 conformance tests
 254     ipp-2.0.test                      - Run IPP/2.0 conformance tests
 255     ipp-2.1.test                      - Run IPP/2.1 conformance tests
 256     ipp-2.2.test                      - Run IPP/2.2 conformance tests
 257     print-job.test                    - Print a file
 258     print-job-and-wait.test           - Print a file and wait for completion
 259     print-job-deflate.test            - Print a file with deflate compression
 260     print-job-gzip.test               - Print a file with gzip compression
 261     print-job-hold.test               - Print a file and hold
 262     print-job-letter.test             - Print a file on US Letter media
 263     print-job-manual.test             - Print a file with manual feed
 264     print-job-media-col.test          - Print a file using &quot;media-col&quot;
 265     print-job-media-needed.test       - Print a file and test for &quot;media-needed&quot;
 266     print-job-password.test           - Print a file with a password/PIN
 267     print-job-raster.test             - Print a generated raster file
 268     print-uri.test                    - Print a URI/URL
 269     set-attrs-hold.test               - Test setting job-hold-until to hold a job
 270     validate-job.test                 - Validate a job ticket
 271 </pre>
 272     <p>The following standard document files are available:
 273 </p>
 274     <pre>
 275     color.jpg                         - A color photo of a flower
 276     document-a4.pdf                   - A 4-page A4 PDF document
 277     document-a4.ps                    - A 4-page A4 PostScript document
 278     document-letter.pdf               - A 4-page US Letter PDF document
 279     document-letter.ps                - A 4-page US Letter PostScript document
 280     gray.jpg                          - A grayscale photo of an Alcatraz doorway
 281     onepage-a4-300-black-1.pwg        - A one page A4 PWG Raster document
 282     onepage-a4.pdf                    - A one page A4 PDF document
 283     onepage-a4.ps                     - A one page A4 PostScript document
 284     onepage-letter-300-black-1.pwg    - A one page US Letter PWG Raster document
 285     onepage-letter.pdf                - A one page US Letter PDF document
 286     onepage-letter.ps                 - A one page US Letter PostScript document
 287     testfile.jpg                      - A color photo collage
 288     testfile.pcl                      - A HP-PCL homage to &quot;The Shining&quot;
 289     testfile.pdf                      - A historical CUPS PDF document
 290     testfile.ps                       - A historical CUPS PostScript document
 291     testfile.txt                      - A plain text homage to &quot;The Shining&quot;
 292 </pre>
 293     <h2 id="ipptool-1.conforming-to">Conforming To</h2>
 294 <p>The
 295 <strong>ipptool</strong>
 296 program is unique to CUPS and conforms to the Internet Printing Protocol up to version 2.2.
 297 </p>
 298     <h2 id="ipptool-1.examples">Examples</h2>
 299 <p>Get a list of completed jobs for &quot;myprinter&quot;:
 300 </p>
 301     <pre>
 302     ipptool ipp://localhost/printers/myprinter get-completed-jobs.test
 303 </pre>
 304     <p>Send email notifications to &quot;user@example.com&quot; when &quot;myprinter&quot; changes:
 305 </p>
 306     <pre>
 307     ipptool -d recipient=mailto:user@example.com \
 308         ipp://localhost/printers/myprinter create-printer-subscription.test
 309 </pre>
 310     <h2 id="ipptool-1.see-also">See Also</h2>
 311 <a href="ipptoolfile.html"><p><strong>ipptoolfile</strong>(5),</a>
 312
 313 IANA IPP Registry (<a href="https://www.iana.org/assignments/ipp-registrations">https://www.iana.org/assignments/ipp-registrations</a>),
 314 PWG Internet Printing Protocol Workgroup (<a href="https://www.pwg.org/ipp">https://www.pwg.org/ipp</a>),
 315 RFC 8011 (<a href="https://datatracker.ietf.org/doc/html/rfc8011">https://datatracker.ietf.org/doc/html/rfc8011</a>)
 316 </p>
 317     <h2 id="ipptool-1.copyright">Copyright</h2>
 318 <p>Copyright &copy; 2021-2024 by OpenPrinting.
 319   </body>
 320 </html>