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