]> git.ipfire.org Git - thirdparty/cups.git/blame - IPPTOOL.txt
Merge changes from CUPS 1.6svn-r10437.
[thirdparty/cups.git] / IPPTOOL.txt
CommitLineData
12f89d24 1IPPTOOL.txt - 2012-02-06
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
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
MS
14
15
16BASIC USAGE
17
10d09e33
MS
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:
39ff2fe7
MS
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
10d09e33
MS
35 To get output suitable for import into a spreadsheet, use the "-c" (CSV)
36 option:
39ff2fe7
MS
37
38 ipptool -c ipp://localhost/printers/myprinter get-jobs.test
39
83e08001 40 which will produce something like this:
39ff2fe7
MS
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
12f89d24
MS
49STANDARD 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-printer-attributes.test Shows printer attributes
58 ipp-1.1.test IPP/1.1 conformance test suite
59 ipp-2.0.test IPP/2.0 conformance test suite
60 ipp-2.1.test IPP/2.1 conformance test suite
61 ipp-2.2.test IPP/2.2 conformance test suite
62 print-job.test Prints a file
63
64
39ff2fe7
MS
65CONFORMANCE TESTS
66
83e08001
MS
67 We provide basic IPP conformance tests for IPP/1.1, IPP/2.0, IPP/2.1, and
68 IPP/2.2. For a given printer URI, the following commands perform tests at
69 each level:
70
9b66acc5
MS
71 ipptool -tf filename [options] -I printer-uri ipp-1.1.test
72 ipptool -tf filename [options] -I -V 2.0 printer-uri ipp-2.0.test
73 ipptool -tf filename [options] -I -V 2.1 printer-uri ipp-2.1.test
74 ipptool -tf filename [options] -I -V 2.2 printer-uri ipp-2.2.test
83e08001
MS
75
76 The filename must use a format supported by the printer; ipptool will guess
77 the MIME media type using the extension, otherwise application/octet stream
78 will be used. The following standard test files are included:
79
80 color.jpg
81 document-a4.pdf
82 document-a4.ps
83 document-letter.pdf
84 document-letter.ps
85 gray.jpg
86 onepage-a4.pdf
87 onepage-a4.ps
88 onepage-letter.pdf
89 onepage-letter.ps
12f89d24
MS
90 testfile.jpg
91 testfile.pdf
92 testfile.ps
93 testfile.txt
94
95 Useful options include the following:
96
97 -4 Connect using IPv4
98 -6 Connect using IPv6
99 -C Send chunked requests (default)
100 -d name=val Define a variable
101 -E Test IPP with HTTP Upgrade to TLS
102 -L Send requests using the Content-Length header (HTTP/1.0)
103 -S Test IPP over HTTPS (default for ipps: URIs)
104 -T seconds Set a timeout for responses in seconds
105 -v Be verbose, showing all attributes sent and received
106
107 The printer-uri must be a URI supported by the printer using the "ipp" or
108 "ipps" scheme, for example:
109
110 ipp://192.168.0.1/ipp
111 ipps://192.168.0.1/ipp/print
83e08001
MS
112
113 Print-by-reference (URL) printing can be tested by defining the document-uri
114 variable to a URL, for example:
115
9b66acc5 116 ipptool -tf filename -d document-uri=url -I printer-uri ipp-1.1.test
83e08001
MS
117
118 The standard test files are available on cups.org under the "test"
119 directory, for example:
39ff2fe7 120
12f89d24
MS
121 ipptool -tf document-a4.pdf \
122 -d document-uri=http://www.cups.org/test/document-a4.pdf \
123 ipp://192.168.0.1/ipp -I -V 2.0 ipp-2.0.test
39ff2fe7 124
9b66acc5
MS
125 The "document" test files contain 4 pages each. Doing the IPP conformance
126 tests will will produce up to 90 pages on various media, depending on the
127 printer.
128
39ff2fe7
MS
129
130READING THE DOCUMENTATION
131
10d09e33 132 The command usage is described in the ipptest(1) man page, while the file
12f89d24
MS
133 format is described in the ipptestfile(5) man page. Both are provided in
134 HTML format with the standalone releases of ipptool.
39ff2fe7
MS
135
136
137GETTING SUPPORT AND OTHER RESOURCES
138
139 If you have problems, READ THE DOCUMENTATION FIRST! We also provide many
140 discussion forums which are available at:
141
142 http://www.cups.org/newsgroups.php
143
144 See the CUPS web site at "http://www.cups.org/" for other resources.
145
146
9b66acc5
MS
147REPORTING BUGS
148
149 If you believe you have discovered a bug in ipptool, please fill out the
150 bug form at:
151
152 http://www.cups.org/str.php
153
154 Be sure to identify the version of CUPS and ipptool (if you downloaded the
155 standalone version) you are using, the printer (if any) and firmware
156 version, and include any files that apply.
157
158 If you downloaded the standalone version of ipptool, please also re-run the
159 test with debug logging enabled. Run the following commands on Windows to
160 enable debug logging:
161
12f89d24 162 setdebug.bat
9b66acc5
MS
163
164 For Linux and Mac OS X use:
165
166 CUPS_DEBUG_LOG=ipptool.log; export CUPS_DEBUG_LOG
167 CUPS_DEBUG_LEVEL=6; export CUPS_DEBUG_LEVEL
168
169 Then when you run the ipptool command a new "ipptool.log" file will be
170 created with detailed information - attach this file to the bug you file
171 as well.
172
173
39ff2fe7
MS
174LEGAL STUFF
175
12f89d24 176 CUPS is Copyright 2007-2012 by Apple Inc. CUPS and the CUPS logo are
39ff2fe7
MS
177 trademarks of Apple Inc.
178
179 The MD5 Digest code is Copyright 1999 Aladdin Enterprises.
180
39ff2fe7
MS
181 CUPS is provided under the terms of version 2 of the GNU General Public
182 License and GNU Library General Public License. This program is distributed
183 in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
184 the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
185 See the "doc/help/license.html" or "LICENSE.txt" files for more information.