man/ipptool.man

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