1 IPPTOOL.txt - 2013-07-15
2 ------------------------
4 See the file CHANGES-IPPTOOL.txt for a list of changes to this software.
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.
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.
20 READING THE DOCUMENTATION
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.
26 Full documentation on the ippfind command can be found in the
27 "man-ippfind.html" file.
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
38 To find all color IPP printers, run:
42 And to run the IPP Everywhere conformance test file on every registered IPP
43 printer, run the following command:
45 ippfind _ipp._tcp,_print --exec ipptool -t '{}' ipp-everywhere.test \;
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"
56 ipptool ipp://localhost/printers/myprinter get-jobs.test
58 which would produce something like this:
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
67 To get output suitable for import into a spreadsheet, use the "-c" (CSV)
70 ipptool -c ipp://localhost/printers/myprinter get-jobs.test
72 which will produce something like this:
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
83 The following standard test files are included with ipptool:
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
89 get-notifications.test Shows events for an ippget
91 get-printer-attributes.test Shows printer attributes
92 get-subscriptions.test Shows a list of subscriptions
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
97 ipp-everywhere.test IPP Everywhere conformance test
99 print-job.test Prints a file
100 print-job-deflate.test Prints a file, compressing with
102 print-job-gzip.test Prints a file, compressing with gzip
103 validate-job.test Validates attributes for a job
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:
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
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:
138 Useful options include the following:
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
149 -X Produce XML (Apple plist) output
151 The printer-uri must be a URI supported by the printer using the "ipp" or
152 "ipps" scheme, for example:
154 ipp://192.168.0.1/ipp
155 ipps://192.168.0.1/ipp/print
157 Print-by-reference (URL) printing can be tested by defining the document-uri
158 variable as a URL, for example:
160 ipptool -tf filename -d document-uri=url -I printer-uri ipp-1.1.test
162 The standard test files are available on cups.org under the "test"
163 directory, for example:
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
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
174 IPP EVERYWHERE TESTING
176 The IPP Everywhere tests use sample PWG raster files available from:
178 ftp://ftp.pwg.org/pub/pwg/ipp/examples
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.
186 GETTING SUPPORT AND OTHER RESOURCES
188 If you have problems, READ THE DOCUMENTATION FIRST! We also provide
189 discussion forums which are available at:
196 If you believe you have discovered a bug in ippfind or ipptool, please fill
199 http://www.cups.org/str.php
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.
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:
211 For Linux and Mac OS X use:
213 CUPS_DEBUG_LOG=ipptool.log; export CUPS_DEBUG_LOG
214 CUPS_DEBUG_LEVEL=6; export CUPS_DEBUG_LEVEL
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
223 CUPS is Copyright 2007-2013 by Apple Inc. CUPS and the CUPS logo are
224 trademarks of Apple Inc.
226 The MD5 Digest code is Copyright 1999 Aladdin Enterprises.
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.