]> git.ipfire.org Git - thirdparty/cups.git/blob - IPPTOOL.txt
150605766d6ca4a4871a7f934bcb219e53c31799
[thirdparty/cups.git] / IPPTOOL.txt
1 IPPTOOL.txt - 2013-05-02
2 ------------------------
3
4 See the file CHANGES-IPPTOOL.txt for a list of changes to this software.
5
6
7 INTRODUCTION
8
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.
14
15
16 BASIC USAGE
17
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:
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
35 To get output suitable for import into a spreadsheet, use the "-c" (CSV)
36 option:
37
38 ipptool -c ipp://localhost/printers/myprinter get-jobs.test
39
40 which will produce something like this:
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
49 STANDARD 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
57 get-notifications.test Shows events for an ippget
58 subscription.
59 get-printer-attributes.test Shows printer attributes
60 get-subscriptions.test Shows a list of subscriptions
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
65 ipp-everywhere.test IPP Everywhere conformance test
66 suite
67 print-job.test Prints a file
68 print-job-deflate.test Prints a file, compressing with
69 deflate.
70 print-job-gzip.test Prints a file, compressing with gzip
71 validate-job.test Validates attributes for a job
72 submission.
73
74
75 CONFORMANCE TESTS
76
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:
80
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
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
100 testfile.jpg
101 testfile.pcl
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
117 -X Produce XML (Apple plist) output
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
124
125 Print-by-reference (URL) printing can be tested by defining the document-uri
126 variable as a URL, for example:
127
128 ipptool -tf filename -d document-uri=url -I printer-uri ipp-1.1.test
129
130 The standard test files are available on cups.org under the "test"
131 directory, for example:
132
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
136
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
141
142 IPP 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
154 READING THE DOCUMENTATION
155
156 The command usage is described in the ipptest(1) man page, while the file
157 format is described in the ipptestfile(5) man page. Both are provided in
158 HTML format with the standalone releases of ipptool.
159
160
161 GETTING 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
171 REPORTING 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
186 setdebug.bat
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
198 LEGAL STUFF
199
200 CUPS is Copyright 2007-2013 by Apple Inc. CUPS and the CUPS logo are
201 trademarks of Apple Inc.
202
203 The MD5 Digest code is Copyright 1999 Aladdin Enterprises.
204
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.