]> git.ipfire.org Git - thirdparty/cups.git/blame - IPPTOOL.txt
<rdar://problem/14016099> ipptool: Use SO_NWRITE socket option to extend timeouts
[thirdparty/cups.git] / IPPTOOL.txt
CommitLineData
94436c5a 1IPPTOOL.txt - 2013-05-02
39ff2fe7
MS
2------------------------
3
9b66acc5
MS
4See the file CHANGES-IPPTOOL.txt for a list of changes to this software.
5
39ff2fe7
MS
6
7INTRODUCTION
8
12f89d24
MS
9 CUPS includes a user program called ipptool that can be used to send
10 arbitrary IPP requests to a CUPS server or IPP printer. This tool started
11 life as part of the CUPS automated test suite and has grown to support
12 complex conformance tests and a simple way to query printer, job, and
13 subscription attributes.
39ff2fe7
MS
14
15
16BASIC USAGE
17
10d09e33
MS
18 The ipptool command requires a printer URI and one or more "test" files that
19 describe the operations, attributes to display, and expected status and
20 attribute values. Several standard files are included with CUPS, for example
21 to show a list of pending print jobs on a CUPS printer called "myprinter"
22 you'd run:
39ff2fe7
MS
23
24 ipptool ipp://localhost/printers/myprinter get-jobs.test
25
26 which would produce something like this:
27
28 job-id job-state job-name job-originating-user-name
29 ------ ------------ ------------ -------------------------
30 72 pending testfile.pdf msweet
31 73 pending testfile.ps msweet
32 74 pending-held testfile.jpg msweet
33 75 pending-held testfile.txt msweet
34
10d09e33
MS
35 To get output suitable for import into a spreadsheet, use the "-c" (CSV)
36 option:
39ff2fe7
MS
37
38 ipptool -c ipp://localhost/printers/myprinter get-jobs.test
39
83e08001 40 which will produce something like this:
39ff2fe7
MS
41
42 job-id,job-state,job-name,job-originating-user-name
43 72,pending,testfile.pdf,msweet
44 73,pending,testfile.ps,msweet
45 74,pending-held,testfile.jpg,msweet
46 75,pending-held,testfile.txt,msweet
47
48
12f89d24
MS
49STANDARD TEST FILES
50
51 The following standard test files are included with ipptool:
52
53 create-printer-subscription.test Creates a printer subscription for
54 state change notifications
55 get-completed-jobs.test Shows a list of completed jobs
56 get-jobs.test Shows a list of pending jobs
db8b865d
MS
57 get-notifications.test Shows events for an ippget
58 subscription.
12f89d24 59 get-printer-attributes.test Shows printer attributes
94436c5a 60 get-subscriptions.test Shows a list of subscriptions
12f89d24
MS
61 ipp-1.1.test IPP/1.1 conformance test suite
62 ipp-2.0.test IPP/2.0 conformance test suite
63 ipp-2.1.test IPP/2.1 conformance test suite
64 ipp-2.2.test IPP/2.2 conformance test suite
db8b865d
MS
65 ipp-everywhere.test IPP Everywhere conformance test
66 suite
12f89d24 67 print-job.test Prints a file
db8b865d
MS
68 print-job-deflate.test Prints a file, compressing with
69 deflate.
70 print-job-gzip.test Prints a file, compressing with gzip
94436c5a
MS
71 validate-job.test Validates attributes for a job
72 submission.
12f89d24
MS
73
74
39ff2fe7
MS
75CONFORMANCE TESTS
76
db8b865d
MS
77 We provide basic IPP conformance tests for IPP/1.1, IPP/2.0, IPP/2.1,
78 IPP/2.2, and IPP Everywhere. For a given printer URI, the following
79 commands perform tests at each level:
83e08001 80
9b66acc5
MS
81 ipptool -tf filename [options] -I printer-uri ipp-1.1.test
82 ipptool -tf filename [options] -I -V 2.0 printer-uri ipp-2.0.test
83 ipptool -tf filename [options] -I -V 2.1 printer-uri ipp-2.1.test
84 ipptool -tf filename [options] -I -V 2.2 printer-uri ipp-2.2.test
83e08001
MS
85
86 The filename must use a format supported by the printer; ipptool will guess
87 the MIME media type using the extension, otherwise application/octet stream
88 will be used. The following standard test files are included:
89
90 color.jpg
91 document-a4.pdf
92 document-a4.ps
93 document-letter.pdf
94 document-letter.ps
95 gray.jpg
96 onepage-a4.pdf
97 onepage-a4.ps
98 onepage-letter.pdf
99 onepage-letter.ps
12f89d24 100 testfile.jpg
a29fd7dd 101 testfile.pcl
12f89d24
MS
102 testfile.pdf
103 testfile.ps
104 testfile.txt
105
106 Useful options include the following:
107
108 -4 Connect using IPv4
109 -6 Connect using IPv6
110 -C Send chunked requests (default)
111 -d name=val Define a variable
112 -E Test IPP with HTTP Upgrade to TLS
113 -L Send requests using the Content-Length header (HTTP/1.0)
114 -S Test IPP over HTTPS (default for ipps: URIs)
115 -T seconds Set a timeout for responses in seconds
116 -v Be verbose, showing all attributes sent and received
db8b865d 117 -X Produce XML (Apple plist) output
12f89d24
MS
118
119 The printer-uri must be a URI supported by the printer using the "ipp" or
120 "ipps" scheme, for example:
121
122 ipp://192.168.0.1/ipp
123 ipps://192.168.0.1/ipp/print
83e08001
MS
124
125 Print-by-reference (URL) printing can be tested by defining the document-uri
94436c5a 126 variable as a URL, for example:
83e08001 127
9b66acc5 128 ipptool -tf filename -d document-uri=url -I printer-uri ipp-1.1.test
83e08001
MS
129
130 The standard test files are available on cups.org under the "test"
131 directory, for example:
39ff2fe7 132
12f89d24
MS
133 ipptool -tf document-a4.pdf \
134 -d document-uri=http://www.cups.org/test/document-a4.pdf \
135 ipp://192.168.0.1/ipp -I -V 2.0 ipp-2.0.test
39ff2fe7 136
9b66acc5
MS
137 The "document" test files contain 4 pages each. Doing the IPP conformance
138 tests will will produce up to 90 pages on various media, depending on the
139 printer.
140
39ff2fe7 141
db8b865d
MS
142IPP EVERYWHERE TESTING
143
144 The IPP Everywhere tests use sample PWG raster files available from:
145
146 ftp://ftp.pwg.org/pub/pwg/ipp/examples
147
148 Extract the corresponding ZIP archives into the current directory before
149 running the ipp-everywhere.test file. The test file will attempt to print
150 each PWG Raster file that is supported by the printer being tested - up to
151 372 pages including the 90 pages produced by the regular IPP test suite.
152
153
39ff2fe7
MS
154READING THE DOCUMENTATION
155
10d09e33 156 The command usage is described in the ipptest(1) man page, while the file
12f89d24
MS
157 format is described in the ipptestfile(5) man page. Both are provided in
158 HTML format with the standalone releases of ipptool.
39ff2fe7
MS
159
160
161GETTING SUPPORT AND OTHER RESOURCES
162
163 If you have problems, READ THE DOCUMENTATION FIRST! We also provide many
164 discussion forums which are available at:
165
166 http://www.cups.org/newsgroups.php
167
168 See the CUPS web site at "http://www.cups.org/" for other resources.
169
170
9b66acc5
MS
171REPORTING BUGS
172
173 If you believe you have discovered a bug in ipptool, please fill out the
174 bug form at:
175
176 http://www.cups.org/str.php
177
178 Be sure to identify the version of CUPS and ipptool (if you downloaded the
179 standalone version) you are using, the printer (if any) and firmware
180 version, and include any files that apply.
181
182 If you downloaded the standalone version of ipptool, please also re-run the
183 test with debug logging enabled. Run the following commands on Windows to
184 enable debug logging:
185
12f89d24 186 setdebug.bat
9b66acc5
MS
187
188 For Linux and Mac OS X use:
189
190 CUPS_DEBUG_LOG=ipptool.log; export CUPS_DEBUG_LOG
191 CUPS_DEBUG_LEVEL=6; export CUPS_DEBUG_LEVEL
192
193 Then when you run the ipptool command a new "ipptool.log" file will be
194 created with detailed information - attach this file to the bug you file
195 as well.
196
197
39ff2fe7
MS
198LEGAL STUFF
199
0fa6c7fa 200 CUPS is Copyright 2007-2013 by Apple Inc. CUPS and the CUPS logo are
39ff2fe7
MS
201 trademarks of Apple Inc.
202
203 The MD5 Digest code is Copyright 1999 Aladdin Enterprises.
204
39ff2fe7
MS
205 CUPS is provided under the terms of version 2 of the GNU General Public
206 License and GNU Library General Public License. This program is distributed
207 in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
208 the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
209 See the "doc/help/license.html" or "LICENSE.txt" files for more information.