man/ipptool.man

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