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