man/ipptool.1

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