1 IPPTOOL.txt - 2013-05-02
2 ------------------------
4 See the file CHANGES-IPPTOOL.txt for a list of changes to this software.
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.
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"
24 ipptool ipp://localhost/printers/myprinter get-jobs.test
26 which would produce something like this:
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
35 To get output suitable for import into a spreadsheet, use the "-c" (CSV)
38 ipptool -c ipp://localhost/printers/myprinter get-jobs.test
40 which will produce something like this:
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
51 The following standard test files are included with ipptool:
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
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
67 print-job.test Prints a file
68 print-job-deflate.test Prints a file, compressing with
70 print-job-gzip.test Prints a file, compressing with gzip
71 validate-job.test Validates attributes for a job
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:
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
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:
106 Useful options include the following:
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
119 The printer-uri must be a URI supported by the printer using the "ipp" or
120 "ipps" scheme, for example:
122 ipp://192.168.0.1/ipp
123 ipps://192.168.0.1/ipp/print
125 Print-by-reference (URL) printing can be tested by defining the document-uri
126 variable as a URL, for example:
128 ipptool -tf filename -d document-uri=url -I printer-uri ipp-1.1.test
130 The standard test files are available on cups.org under the "test"
131 directory, for example:
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
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
142 IPP EVERYWHERE TESTING
144 The IPP Everywhere tests use sample PWG raster files available from:
146 ftp://ftp.pwg.org/pub/pwg/ipp/examples
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.
154 READING THE DOCUMENTATION
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.
161 GETTING SUPPORT AND OTHER RESOURCES
163 If you have problems, READ THE DOCUMENTATION FIRST! We also provide many
164 discussion forums which are available at:
166 http://www.cups.org/newsgroups.php
168 See the CUPS web site at "http://www.cups.org/" for other resources.
173 If you believe you have discovered a bug in ipptool, please fill out the
176 http://www.cups.org/str.php
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.
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:
188 For Linux and Mac OS X use:
190 CUPS_DEBUG_LOG=ipptool.log; export CUPS_DEBUG_LOG
191 CUPS_DEBUG_LEVEL=6; export CUPS_DEBUG_LEVEL
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
200 CUPS is Copyright 2007-2013 by Apple Inc. CUPS and the CUPS logo are
201 trademarks of Apple Inc.
203 The MD5 Digest code is Copyright 1999 Aladdin Enterprises.
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.