IPPTOOL.txt

   1 IPPTOOL.txt - 2013-01-10
   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-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
  65 CONFORMANCE TESTS
  66
  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
  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
  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
  90         testfile.jpg
  91         testfile.pcl
  92         testfile.pdf
  93         testfile.ps
  94         testfile.txt
  95
  96     Useful options include the following:
  97
  98         -4           Connect using IPv4
  99         -6           Connect using IPv6
 100         -C           Send chunked requests (default)
 101         -d name=val  Define a variable
 102         -E           Test IPP with HTTP Upgrade to TLS
 103         -L           Send requests using the Content-Length header (HTTP/1.0)
 104         -S           Test IPP over HTTPS (default for ipps: URIs)
 105         -T seconds   Set a timeout for responses in seconds
 106         -v           Be verbose, showing all attributes sent and received
 107
 108     The printer-uri must be a URI supported by the printer using the "ipp" or
 109     "ipps" scheme, for example:
 110
 111         ipp://192.168.0.1/ipp
 112         ipps://192.168.0.1/ipp/print
 113
 114     Print-by-reference (URL) printing can be tested by defining the document-uri
 115     variable to a URL, for example:
 116
 117         ipptool -tf filename -d document-uri=url -I printer-uri ipp-1.1.test
 118
 119     The standard test files are available on cups.org under the "test"
 120     directory, for example:
 121
 122         ipptool -tf document-a4.pdf \
 123             -d document-uri=http://www.cups.org/test/document-a4.pdf \
 124             ipp://192.168.0.1/ipp -I -V 2.0 ipp-2.0.test
 125
 126     The "document" test files contain 4 pages each.  Doing the IPP conformance
 127     tests will will produce up to 90 pages on various media, depending on the
 128     printer.
 129
 130
 131 READING THE DOCUMENTATION
 132
 133     The command usage is described in the ipptest(1) man page, while the file
 134     format is described in the ipptestfile(5) man page.  Both are provided in
 135     HTML format with the standalone releases of ipptool.
 136
 137
 138 GETTING SUPPORT AND OTHER RESOURCES
 139
 140     If you have problems, READ THE DOCUMENTATION FIRST!  We also provide many
 141     discussion forums which are available at:
 142
 143         http://www.cups.org/newsgroups.php
 144
 145     See the CUPS web site at "http://www.cups.org/" for other resources.
 146
 147
 148 REPORTING BUGS
 149
 150     If you believe you have discovered a bug in ipptool, please fill out the
 151     bug form at:
 152
 153         http://www.cups.org/str.php
 154
 155     Be sure to identify the version of CUPS and ipptool (if you downloaded the
 156     standalone version) you are using, the printer (if any) and firmware
 157     version, and include any files that apply.
 158
 159     If you downloaded the standalone version of ipptool, please also re-run the
 160     test with debug logging enabled.  Run the following commands on Windows to
 161     enable debug logging:
 162
 163         setdebug.bat
 164
 165     For Linux and Mac OS X use:
 166
 167         CUPS_DEBUG_LOG=ipptool.log; export CUPS_DEBUG_LOG
 168         CUPS_DEBUG_LEVEL=6; export CUPS_DEBUG_LEVEL
 169
 170     Then when you run the ipptool command a new "ipptool.log" file will be
 171     created with detailed information - attach this file to the bug you file
 172     as well.
 173
 174
 175 LEGAL STUFF
 176
 177     CUPS is Copyright 2007-2013 by Apple Inc.  CUPS and the CUPS logo are
 178     trademarks of Apple Inc.
 179
 180     The MD5 Digest code is Copyright 1999 Aladdin Enterprises.
 181
 182     CUPS is provided under the terms of version 2 of the GNU General Public
 183     License and GNU Library General Public License. This program is distributed
 184     in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
 185     the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 186     See the "doc/help/license.html" or "LICENSE.txt" files for more information.