IPPTOOL.txt

   1 IPPTOOL.txt - 2013-06-06
   2 ------------------------
   3
   4 See the file CHANGES-IPPTOOL.txt for a list of changes to this software.
   5
   6
   7 INTRODUCTION
   8
   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.
  14
  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.
  18
  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
  39
  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:
  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
  57     To get output suitable for import into a spreadsheet, use the "-c" (CSV)
  58     option:
  59
  60         ipptool -c ipp://localhost/printers/myprinter get-jobs.test
  61
  62     which will produce something like this:
  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
  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
  79         get-notifications.test              Shows events for an ippget
  80                                             subscription.
  81         get-printer-attributes.test         Shows printer attributes
  82         get-subscriptions.test              Shows a list of subscriptions
  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
  87         ipp-everywhere.test                 IPP Everywhere conformance test
  88                                             suite
  89         print-job.test                      Prints a file
  90         print-job-deflate.test              Prints a file, compressing with
  91                                             deflate.
  92         print-job-gzip.test                 Prints a file, compressing with gzip
  93         validate-job.test                   Validates attributes for a job
  94                                             submission.
  95
  96
  97 CONFORMANCE TESTS
  98
  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:
 102
 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
 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
 122         testfile.jpg
 123         testfile.pcl
 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
 139         -X           Produce XML (Apple plist) output
 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
 146
 147     Print-by-reference (URL) printing can be tested by defining the document-uri
 148     variable as a URL, for example:
 149
 150         ipptool -tf filename -d document-uri=url -I printer-uri ipp-1.1.test
 151
 152     The standard test files are available on cups.org under the "test"
 153     directory, for example:
 154
 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
 158
 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
 163
 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
 176 READING THE DOCUMENTATION
 177
 178     The command usage is described in the ipptest(1) man page, while the file
 179     format is described in the ipptestfile(5) man page.  Both are provided in
 180     HTML format with the standalone releases of ipptool.
 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
 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
 208         setdebug.bat
 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
 220 LEGAL STUFF
 221
 222     CUPS is Copyright 2007-2013 by Apple Inc.  CUPS and the CUPS logo are
 223     trademarks of Apple Inc.
 224
 225     The MD5 Digest code is Copyright 1999 Aladdin Enterprises.
 226
 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.