man/ipptool.1

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