IPPTOOL.txt

   1 IPPTOOL.txt - 2013-05-02
   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
  16 BASIC USAGE
  17
  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:
  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
  35     To get output suitable for import into a spreadsheet, use the "-c" (CSV)
  36     option:
  37
  38         ipptool -c ipp://localhost/printers/myprinter get-jobs.test
  39
  40     which will produce something like this:
  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
  49 STANDARD 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-notifications.test              Shows events for an ippget
  58                                             subscription.
  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
  66                                             suite
  67         print-job.test                      Prints a file
  68         print-job-deflate.test              Prints a file, compressing with
  69                                             deflate.
  70         print-job-gzip.test                 Prints a file, compressing with gzip
  71         validate-job.test                   Validates attributes for a job
  72                                             submission.
  73
  74
  75 CONFORMANCE TESTS
  76
  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:
  80
  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
  85
  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:
  89
  90         color.jpg
  91         document-a4.pdf
  92         document-a4.ps
  93         document-letter.pdf
  94         document-letter.ps
  95         gray.jpg
  96         onepage-a4.pdf
  97         onepage-a4.ps
  98         onepage-letter.pdf
  99         onepage-letter.ps
 100         testfile.jpg
 101         testfile.pcl
 102         testfile.pdf
 103         testfile.ps
 104         testfile.txt
 105
 106     Useful options include the following:
 107
 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
 118
 119     The printer-uri must be a URI supported by the printer using the "ipp" or
 120     "ipps" scheme, for example:
 121
 122         ipp://192.168.0.1/ipp
 123         ipps://192.168.0.1/ipp/print
 124
 125     Print-by-reference (URL) printing can be tested by defining the document-uri
 126     variable as a URL, for example:
 127
 128         ipptool -tf filename -d document-uri=url -I printer-uri ipp-1.1.test
 129
 130     The standard test files are available on cups.org under the "test"
 131     directory, for example:
 132
 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
 136
 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
 139     printer.
 140
 141
 142 IPP EVERYWHERE TESTING
 143
 144     The IPP Everywhere tests use sample PWG raster files available from:
 145
 146         ftp://ftp.pwg.org/pub/pwg/ipp/examples
 147
 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.
 152
 153
 154 READING THE DOCUMENTATION
 155
 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.
 159
 160
 161 GETTING SUPPORT AND OTHER RESOURCES
 162
 163     If you have problems, READ THE DOCUMENTATION FIRST!  We also provide many
 164     discussion forums which are available at:
 165
 166         http://www.cups.org/newsgroups.php
 167
 168     See the CUPS web site at "http://www.cups.org/" for other resources.
 169
 170
 171 REPORTING BUGS
 172
 173     If you believe you have discovered a bug in ipptool, please fill out the
 174     bug form at:
 175
 176         http://www.cups.org/str.php
 177
 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.
 181
 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:
 185
 186         setdebug.bat
 187
 188     For Linux and Mac OS X use:
 189
 190         CUPS_DEBUG_LOG=ipptool.log; export CUPS_DEBUG_LOG
 191         CUPS_DEBUG_LEVEL=6; export CUPS_DEBUG_LEVEL
 192
 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
 195     as well.
 196
 197
 198 LEGAL STUFF
 199
 200     CUPS is Copyright 2007-2013 by Apple Inc.  CUPS and the CUPS logo are
 201     trademarks of Apple Inc.
 202
 203     The MD5 Digest code is Copyright 1999 Aladdin Enterprises.
 204
 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.