man/ipptool.man

   1 .\"
   2 .\" ipptool man page.
   3 .\"
   4 .\" Copyright 2010-2017 by Apple Inc.
   5 .\"
   6 .\" These coded instructions, statements, and computer programs are the
   7 .\" property of Apple Inc. and are protected by Federal copyright
   8 .\" law.  Distribution and use rights are outlined in the file "LICENSE.txt"
   9 .\" which should have been included with this file.  If this file is
  10 .\" file is missing or damaged, see the license at "http://www.cups.org/".
  11 .\"
  12 .TH ipptool 1 "CUPS" "4 August 2017" "Apple Inc."
  13 .SH NAME
  14 ipptool \- perform internet printing protocol requests
  15 .SH SYNOPSIS
  16 .B ipptool
  17 [
  18 .B \-\-help
  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 .B \-\-stop-after-include-error
  96 Tells
  97 .B ipptool
  98 to stop if an error occurs in an included file. Normally
  99 .B ipptool
 100 will continue with subsequent tests after the INCLUDE directive.
 101 .TP 5
 102 .B \-\-version
 103 Shows the version of
 104 .B ipptool
 105 being used.
 106 .TP 5
 107 .B \-4
 108 Specifies that
 109 .B ipptool
 110 must connect to the printer or server using IPv4.
 111 .TP 5
 112 .B \-6
 113 Specifies that
 114 .B ipptool
 115 must connect to the printer or server using IPv6.
 116 .TP 5
 117 .B \-C
 118 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.
 119 The default is to use "Transfer\-Encoding: chunked" for requests with attached files and "Content\-Length:" for requests without attached files.
 120 .TP 5
 121 .B \-E
 122 Forces TLS encryption when connecting to the server using the HTTP "Upgrade" header.
 123 .TP 5
 124 .B \-I
 125 Specifies that
 126 .B ipptool
 127 will continue past errors.
 128 .TP 5
 129 .B \-L
 130 Specifies that requests should be sent using the HTTP/1.0 "Content\-Length:" header, which is required for conformance by all versions of IPP.
 131 The default is to use "Transfer\-Encoding: chunked" for requests with attached files and "Content\-Length:" for requests without attached files.
 132 .TP 5
 133 .BI \-P \ filename.plist
 134 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).
 135 This option is incompatible with the \fB\-i\fR (interval) and \fB\-n\fR (repeat\-count) options.
 136 .TP 5
 137 .B \-S
 138 Forces (dedicated) TLS encryption when connecting to the server.
 139 .TP 5
 140 .BI \-T \ seconds
 141 Specifies a timeout for IPP requests in seconds.
 142 .TP 5
 143 .BI \-V \ version
 144 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.
 145 .TP 5
 146 .B \-X
 147 Specifies that XML (Apple plist) output is desired instead of the plain text report.
 148 This option is incompatible with the \fB\-i\fR (interval) and \fB\-n\fR (repeat\-count) options.
 149 .TP 5
 150 .B \-c
 151 Specifies that CSV (comma\-separated values) output is desired instead of the plain text output.
 152 .TP 5
 153 .BI \-d \ name=value
 154 Defines the named variable.
 155 .TP 5
 156 .BI \-f \ filename
 157 Defines the default request filename for tests.
 158 .TP 5
 159 .B \-h
 160 Validate HTTP response headers.
 161 .TP 5
 162 .BI \-i \ seconds
 163 Specifies that the (last)
 164 .I testfile
 165 should be repeated at the specified interval.
 166 This option is incompatible with the \fB\-X\fR (XML plist output) option.
 167 .TP 5
 168 .B \-l
 169 Specifies that plain text output is desired.
 170 .TP 5
 171 .BI \-n \ repeat\-count
 172 Specifies that the (last)
 173 .I testfile
 174 should be repeated the specified number of times.
 175 This option is incompatible with the \fI\-X\fR (XML plist output) option.
 176 .TP 5
 177 .B \-q
 178 Be quiet and produce no output.
 179 .TP 5
 180 .B \-t
 181 Specifies that CUPS test report output is desired instead of the plain text output.
 182 .TP 5
 183 .B \-v
 184 Specifies that all request and response attributes should be output in CUPS test mode (\fB\-t\fR).
 185 This is the default for XML output.
 186 .SH EXIT STATUS
 187 The
 188 .B ipptool
 189 program returns 0 if all tests were successful and 1 otherwise.
 190 .SH FILES
 191 The following standard files are available:
 192 .nf
 193 .I color.jpg
 194 .I create\-printer\-subscription.test
 195 .I document\-a4.pdf
 196 .I document\-a4.ps
 197 .I document\-letter.pdf
 198 .I document\-letter.ps
 199 .I get\-completed\-jobs.test
 200 .I get\-jobs.test
 201 .I get\-notifications.test
 202 .I get\-printer\-attributes.test
 203 .I get\-subscriptions.test
 204 .I gray.jpg
 205 .I ipp\-1.1.test
 206 .I ipp\-2.0.test
 207 .I ipp\-2.1.test
 208 .I ipp\-2.2.test
 209 .I ipp\-everywhere.test
 210 .I onepage\-a4.pdf
 211 .I onepage\-a4.ps
 212 .I onepage\-letter.pdf
 213 .I onepage\-letter.ps
 214 .I print\-job.test
 215 .I print\-job\-deflate.test
 216 .I print\-job\-gzip.test
 217 .I testfile.jpg
 218 .I testfile.pcl
 219 .I testfile.pdf
 220 .I testfile.ps
 221 .I testfile.txt
 222 .I validate\-job.test
 223 .fi
 224 .SH CONFORMING TO
 225 The
 226 .B ipptool
 227 program is unique to CUPS and conforms to the Internet Printing Protocol up to version 2.2.
 228 .SH EXAMPLES
 229 Get a list of completed jobs for "myprinter":
 230 .nf
 231
 232     ipptool ipp://localhost/printers/myprinter get\-completed\-jobs.test
 233 .fi
 234 .LP
 235 Send email notifications to "user@example.com" when "myprinter" changes:
 236 .nf
 237
 238     ipptool \-d recipient=mailto:user@example.com \\
 239         ipp://localhost/printers/myprinter create\-printer\-subscription.test
 240 .fi
 241 .SH SEE ALSO
 242 .BR ipptoolfile (5),
 243 IANA IPP Registry (http://www.iana.org/assignments/ipp\-registrations),
 244 PWG Internet Printing Protocol Workgroup (http://www.pwg.org/ipp)
 245 RFC 8011 (http://tools.ietf.org/html/rfc8011),
 246 .SH COPYRIGHT
 247 Copyright \[co] 2007-2017 by Apple Inc.