doc/help/man-ipptool.html

   1 <!DOCTYPE HTML>
   2 <html>
   3 <!-- SECTION: Man Pages -->
   4 <head>
   5         <link rel="stylesheet" type="text/css" href="../cups-printable.css">
   6         <title>ipptool(1)</title>
   7 </head>
   8 <body>
   9 <h1 class="title">ipptool(1)</h1>
  10 <h2 class="title"><a name="NAME">Name</a></h2>
  11 ipptool - perform internet printing protocol requests
  12 <h2 class="title"><a name="SYNOPSIS">Synopsis</a></h2>
  13 <b>ipptool</b>
  14 [
  15 <b>--help</b>
  16 ] [
  17 <b>--ippserver</b>
  18 <i>filename</i>
  19 ] [
  20 <b>--stop-after-include-error</b>
  21 ] [
  22 <b>--version</b>
  23 ] [
  24 <b>-4</b>
  25 ] [
  26 <b>-6</b>
  27 ] [
  28 <b>-C</b>
  29 ] [
  30 <b>-E</b>
  31 ] [
  32 <b>-I</b>
  33 ] [
  34 <b>-L</b>
  35 ] [
  36 <b>-P</b>
  37 <i>filename.plist</i>
  38 ] [
  39 <b>-R</b>
  40 ] [
  41 <b>-S</b>
  42 ] [
  43 <b>-T</b>
  44 <i>seconds</i>
  45 ] [
  46 <b>-V</b>
  47 <i>version</i>
  48 ] [
  49 <b>-X</b>
  50 ] [
  51 <b>-c</b>
  52 ] [
  53 <b>-d</b>
  54 <i>name=value</i>
  55 ] [
  56 <b>-f</b>
  57 <i>filename</i>
  58 ] [
  59 <b>-h</b>
  60 ] [
  61 <b>-i</b>
  62 <i>seconds</i>
  63 ] [
  64 <b>-n</b>
  65 <i>repeat-count</i>
  66 ] [
  67 <b>-q</b>
  68 ] [
  69 <b>-t</b>
  70 ] [
  71 <b>-v</b><b>]</b>
  72 <i>printer-uri</i>
  73 <i>testfile</i>
  74 [ ...
  75 <i>testfile</i>
  76 ]
  77 <h2 class="title"><a name="DESCRIPTION">Description</a></h2>
  78 <b>ipptool</b>
  79 sends IPP requests to the specified
  80 <i>printer-uri</i>
  81 and tests and/or displays the results.
  82 Each named
  83 <i>testfile</i>
  84 defines one or more requests, including the expected response status, attributes, and values.
  85 Output is either a plain text, formatted text, CSV, or XML report on the standard output, with a non-zero exit status indicating that one or more tests have failed.
  86 The
  87 <i>testfile</i>
  88 format is described in
  89 <b>ipptoolfile</b>(5).
  90 <h2 class="title"><a name="OPTIONS">Options</a></h2>
  91 The following options are recognized by
  92 <b>ipptool:</b>
  93 <dl class="man">
  94 <dt><b>--help</b>
  95 <dd style="margin-left: 5.0em">Shows program help.
  96 <dt><b>--ippserver </b><i>filename</i>
  97 <dd style="margin-left: 5.0em">Specifies that the test results should be written to the named
  98 <b>ippserver</b>
  99 attributes file.
 100 <dt><b>--stop-after-include-error</b>
 101 <dd style="margin-left: 5.0em">Tells
 102 <b>ipptool</b>
 103 to stop if an error occurs in an included file. Normally
 104 <b>ipptool</b>
 105 will continue with subsequent tests after the INCLUDE directive.
 106 <dt><b>--version</b>
 107 <dd style="margin-left: 5.0em">Shows the version of
 108 <b>ipptool</b>
 109 being used.
 110 <dt><b>-4</b>
 111 <dd style="margin-left: 5.0em">Specifies that
 112 <b>ipptool</b>
 113 must connect to the printer or server using IPv4.
 114 <dt><b>-6</b>
 115 <dd style="margin-left: 5.0em">Specifies that
 116 <b>ipptool</b>
 117 must connect to the printer or server using IPv6.
 118 <dt><b>-C</b>
 119 <dd style="margin-left: 5.0em">Specifies that requests should be sent using the HTTP/1.1 "Transfer-Encoding: chunked" header, which is required for conformance by all versions of IPP.
 120 The default is to use "Transfer-Encoding: chunked" for requests with attached files and "Content-Length:" for requests without attached files.
 121 <dt><b>-E</b>
 122 <dd style="margin-left: 5.0em">Forces TLS encryption when connecting to the server using the HTTP "Upgrade" header.
 123 <dt><b>-I</b>
 124 <dd style="margin-left: 5.0em">Specifies that
 125 <b>ipptool</b>
 126 will continue past errors.
 127 <dt><b>-L</b>
 128 <dd style="margin-left: 5.0em">Specifies that requests should be sent using the HTTP/1.0 "Content-Length:" header, which is required for conformance by all versions of IPP.
 129 The default is to use "Transfer-Encoding: chunked" for requests with attached files and "Content-Length:" for requests without attached files.
 130 <dt><b>-P</b><i> filename.plist</i>
 131 <dd style="margin-left: 5.0em">Specifies that the test results should be written to the named XML (Apple plist) file in addition to the regular test report (<b>-t</b>).
 132 This option is incompatible with the <b>-i</b> (interval) and <b>-n</b> (repeat-count) options.
 133 <dt><b>-R</b>
 134 <dd style="margin-left: 5.0em">Retries tests when the "server-error-busy" status code is returned.
 135 <dt><b>-S</b>
 136 <dd style="margin-left: 5.0em">Forces (dedicated) TLS encryption when connecting to the server.
 137 <dt><b>-T</b><i> seconds</i>
 138 <dd style="margin-left: 5.0em">Specifies a timeout for IPP requests in seconds.
 139 <dt><b>-V</b><i> version</i>
 140 <dd style="margin-left: 5.0em">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.
 141 <dt><b>-X</b>
 142 <dd style="margin-left: 5.0em">Specifies that XML (Apple plist) output is desired instead of the plain text report.
 143 This option is incompatible with the <b>-i</b> (interval) and <b>-n</b> (repeat-count) options.
 144 <dt><b>-c</b>
 145 <dd style="margin-left: 5.0em">Specifies that CSV (comma-separated values) output is desired instead of the plain text output.
 146 <dt><b>-d</b><i> name=value</i>
 147 <dd style="margin-left: 5.0em">Defines the named variable.
 148 <dt><b>-f</b><i> filename</i>
 149 <dd style="margin-left: 5.0em">Defines the default request filename for tests.
 150 <dt><b>-h</b>
 151 <dd style="margin-left: 5.0em">Validate HTTP response headers.
 152 <dt><b>-i</b><i> seconds</i>
 153 <dd style="margin-left: 5.0em">Specifies that the (last)
 154 <i>testfile</i>
 155 should be repeated at the specified interval.
 156 This option is incompatible with the <b>-X</b> (XML plist output) option.
 157 <dt><b>-l</b>
 158 <dd style="margin-left: 5.0em">Specifies that plain text output is desired.
 159 <dt><b>-n</b><i> repeat-count</i>
 160 <dd style="margin-left: 5.0em">Specifies that the (last)
 161 <i>testfile</i>
 162 should be repeated the specified number of times.
 163 This option is incompatible with the <i>-X</i> (XML plist output) option.
 164 <dt><b>-q</b>
 165 <dd style="margin-left: 5.0em">Be quiet and produce no output.
 166 <dt><b>-t</b>
 167 <dd style="margin-left: 5.0em">Specifies that CUPS test report output is desired instead of the plain text output.
 168 <dt><b>-v</b>
 169 <dd style="margin-left: 5.0em">Specifies that all request and response attributes should be output in CUPS test mode (<b>-t</b>).
 170 This is the default for XML output.
 171 </dl>
 172 <h2 class="title"><a name="EXIT_STATUS">Exit Status</a></h2>
 173 The
 174 <b>ipptool</b>
 175 program returns 0 if all tests were successful and 1 otherwise.
 176 <h2 class="title"><a name="FILES">Files</a></h2>
 177 The following standard files are available:
 178 <pre class="man">
 179 <i>color.jpg</i>
 180 <i>create-printer-subscription.test</i>
 181 <i>document-a4.pdf</i>
 182 <i>document-a4.ps</i>
 183 <i>document-letter.pdf</i>
 184 <i>document-letter.ps</i>
 185 <i>get-completed-jobs.test</i>
 186 <i>get-jobs.test</i>
 187 <i>get-notifications.test</i>
 188 <i>get-printer-attributes.test</i>
 189 <i>get-subscriptions.test</i>
 190 <i>gray.jpg</i>
 191 <i>ipp-1.1.test</i>
 192 <i>ipp-2.0.test</i>
 193 <i>ipp-2.1.test</i>
 194 <i>ipp-2.2.test</i>
 195 <i>ipp-everywhere.test</i>
 196 <i>onepage-a4.pdf</i>
 197 <i>onepage-a4.ps</i>
 198 <i>onepage-letter.pdf</i>
 199 <i>onepage-letter.ps</i>
 200 <i>print-job.test</i>
 201 <i>print-job-deflate.test</i>
 202 <i>print-job-gzip.test</i>
 203 <i>testfile.jpg</i>
 204 <i>testfile.pcl</i>
 205 <i>testfile.pdf</i>
 206 <i>testfile.ps</i>
 207 <i>testfile.txt</i>
 208 <i>validate-job.test</i>
 209 </pre>
 210 <h2 class="title"><a name="CONFORMING_TO">Conforming To</a></h2>
 211 The
 212 <b>ipptool</b>
 213 program is unique to CUPS and conforms to the Internet Printing Protocol up to version 2.2.
 214 <h2 class="title"><a name="EXAMPLES">Examples</a></h2>
 215 Get a list of completed jobs for "myprinter":
 216 <pre class="man">
 217
 218     ipptool ipp://localhost/printers/myprinter get-completed-jobs.test
 219 </pre>
 220 <p>Send email notifications to "user@example.com" when "myprinter" changes:
 221 <pre class="man">
 222
 223     ipptool -d recipient=mailto:user@example.com \
 224         ipp://localhost/printers/myprinter create-printer-subscription.test
 225 </pre>
 226 <h2 class="title"><a name="SEE_ALSO">See Also</a></h2>
 227 <b>ipptoolfile</b>(5),
 228 IANA IPP Registry (<a href="http://www.iana.org/assignments/ipp\-registrations)">http://www.iana.org/assignments/ipp\-registrations)</a>,
 229 PWG Internet Printing Protocol Workgroup (<a href="http://www.pwg.org/ipp">http://www.pwg.org/ipp</a>)
 230 RFC 8011 (<a href="http://tools.ietf.org/html/rfc8011)">http://tools.ietf.org/html/rfc8011)</a>,
 231 <h2 class="title"><a name="COPYRIGHT">Copyright</a></h2>
 232 Copyright &copy; 2007-2021 by Apple Inc.
 233
 234 </body>
 235 </html>