man/ippeveprinter.man

   1 .\"
   2 .\" ippeveprinter man page for CUPS.
   3 .\"
   4 .\" Copyright © 2014-2019 by Apple Inc.
   5 .\"
   6 .\" Licensed under Apache License v2.0.  See the file "LICENSE" for more
   7 .\" information.
   8 .\"
   9 .TH ippeveprinter 1 "CUPS" "24 April 2019" "Apple Inc."
  10 .SH NAME
  11 ippeveprinter \- an ipp everywhere printer application for cups
  12 .SH SYNOPSIS
  13 .B ippeveprinter
  14 [
  15 .B \-\-help
  16 ] [
  17 .B \-\-no\-web\-forms
  18 ] [
  19 .B \-\-version
  20 ] [
  21 .B \-2
  22 ] [
  23 .B \-D
  24 .I device-uri
  25 ] [
  26 .B \-K
  27 .I keypath
  28 ] [
  29 .B \-M
  30 .I manufacturer
  31 ] [
  32 .B \-P
  33 .I filename.ppd
  34 ] [
  35 .B \-V
  36 .I ipp-version
  37 ] [
  38 .B \-a
  39 .I filename.conf
  40 ] [
  41 .B \-c
  42 .I command
  43 ] [
  44 .B \-d
  45 .I spool-directory
  46 ] [
  47 .B \-f
  48 .I type/subtype[,...]
  49 ] [
  50 .B \-i
  51 .I iconfile.png
  52 ] [
  53 .B \-k
  54 ] [
  55 .B \-l
  56 .I location
  57 ] [
  58 .B \-m
  59 .I model
  60 ] [
  61 .B \-n
  62 .I hostname
  63 ] [
  64 .B \-p
  65 .I port
  66 ] [
  67 .B \-r
  68 .I subtype[,subtype]
  69 ] [
  70 .B \-s
  71 .I speed[,color-speed]
  72 ] [
  73 .B \-v[vvv]
  74 ]
  75 .I service-name
  76 .SH DESCRIPTION
  77 .B ippeveprinter
  78 is a simple Internet Printing Protocol (IPP) server conforming to the IPP Everywhere (PWG 5100.14) specification. It can be used to test client software or act as a very basic print server that runs a command for every job that is printed.
  79 .SH OPTIONS
  80 The following options are recognized by
  81 .B ippeveprinter:
  82 .TP 5
  83 .B \-\-help
  84 Show program usage.
  85 .TP 5
  86 .B \-\-no\-web\-forms
  87 Disable the web interface forms used to update the media and supply levels.
  88 .TP 5
  89 .B \-\-version
  90 Show the CUPS version.
  91 .TP 5
  92 .B \-2
  93 Report support for two-sided (duplex) printing.
  94 .TP 5
  95 \fB\-D \fIdevice-uri\fR
  96 Set the device URI for print output.
  97 The URI can be a filename, directory, or a network socket URI of the form "socket://ADDRESS[:PORT]" (where the default port number is 9100).
  98 When specifying a directory,
  99 .B ippeveprinter
 100 will create an output file using the job ID and name.
 101 .TP 5
 102 \fB\-M \fImanufacturer\fR
 103 Set the manufacturer of the printer.
 104 The default is "Example".
 105 .TP 5
 106 \fB\-P \fIfilename.ppd\fR
 107 Load printer attributes from the specified PPD file.
 108 This option is typically used in conjunction with the
 109 .BR ippeveps (7)
 110 printer command ("\-c ippeveps").
 111 .TP 5
 112 \fB\-V 1.1\fR
 113 .TP 5
 114 \fB\-V 2.0\fR
 115 Specifies the maximum IPP version to report.
 116 2.0 is the default.
 117 .TP 5
 118 \fB\-c \fIcommand\fR
 119 Run the specified command for each document that is printed.
 120 If "command" is not an absolute path ("/path/to/command"),
 121 .B ippeveprinter
 122 looks for the command in the "ippeveprinter" subdirectory of the CUPS binary directory, typically /usr/lib/cups/ippeveprinter or /usr/libexec/cups/ippeveprinter.
 123 The
 124 .BR cups-config (1)
 125 command can be used to discover the correct binary directory ("cups-config --serverbin").
 126 In addition, the CUPS_SERVERBIN environment variable can be used to override the default location of this directory - see the
 127 .BR cups (1)
 128 man page for more details.
 129 .TP 5
 130 \fB\-d \fIspool-directory\fR
 131 Specifies the directory that will hold the print files.
 132 The default is a directory under the user's current temporary directory.
 133 .TP 5
 134 \fB\-f \fItype/subtype[,...]\fR
 135 Specifies a list of MIME media types that the server will accept.
 136 The default depends on the type of printer created.
 137 .TP 5
 138 \fB\-i \fIiconfile.png\fR
 139 Specifies the printer icon file for the server.
 140 The file must be a PNG format image.
 141 The default is an internally-provided PNG image.
 142 .TP 5
 143 .B \-k
 144 Keeps the print documents in the spool directory rather than deleting them.
 145 .TP 5
 146 \fB\-l \fIlocation\fR
 147 Specifies the human-readable location string that is reported by the server.
 148 The default is the empty string.
 149 .TP 5
 150 \fB\-m \fImodel\fR
 151 Specifies the model name of the printer.
 152 The default is "Printer".
 153 .TP 5
 154 \fB\-n \fIhostname\fR
 155 Specifies the hostname that is reported by the server.
 156 The default is the name returned by the
 157 .BR hostname (1)
 158 command.
 159 .TP 5
 160 \fB\-p \fIport\fR
 161 Specifies the port number to listen on.
 162 The default is a user-specific number from 8000 to 8999.
 163 .TP 5
 164 \fB\-r \fIsubtype[,subtype]\fR
 165 Specifies the DNS-SD subtype(s) to advertise.
 166 Separate multiple subtypes with a comma.
 167 The default is "_print".
 168 .TP 5
 169 \fB\-s \fIspeed[,color-speed]\fR
 170 Specifies the printer speed in pages per minute.
 171 If two numbers are specified and the second number is greater than zero, the server will report support for color printing.
 172 The default is "10,0".
 173 .TP 5
 174 .B \-v[vvv]
 175 Be (very) verbose when logging activity to standard error.
 176 .SH EXIT STATUS
 177 The
 178 .B ippeveprinter
 179 program returns 1 if it is unable to process the command-line arguments or register the IPP service.
 180 Otherwise
 181 .B ippeveprinter
 182 will run continuously until terminated.
 183 .SH CONFORMING TO
 184 The
 185 .B ippeveprinter
 186 program is unique to CUPS and conforms to the IPP Everywhere (PWG 5100.14) specification.
 187 .SH ENVIRONMENT
 188 .B ippeveprinter
 189 adds environment variables starting with "IPP_" for all IPP Job attributes in the print request.
 190 For example, when executing a command for an IPP Job containing the "media" Job Template attribute, the "IPP_MEDIA" environment variable will be set to the value of that attribute.
 191 .LP
 192 In addition, all IPP "xxx-default" Printer Description attributes are added to the environment.
 193 For example, the "IPP_MEDIA_DEFAULT" environment variable will be set to the default value for the "media" Job Template attribute.
 194 .LP
 195 Enumerated values are converted to their keyword equivalents.
 196 For example, a "print-quality" Job Template attribute with a enum value of 3 will become the "IPP_PRINT_QUALITY" environment variable with a value of "draft".
 197 This string conversion only happens for standard Job Template attributes, currently "finishings", "orientation-requested", and "print-quality".
 198 .LP
 199 Finally, the "CONTENT_TYPE" environment variable contains the MIME media type of the document being printed, the "DEVICE_URI" environment variable contains the device URI as specified with the "\-D" option, and the "PPD" environment variable contains the PPD filename as specified with the "\-P" option.
 200 .SH COMMAND OUTPUT
 201 Unless they communicate directly with a printer, print commands send printer-ready data to the standard output.
 202 .LP
 203 Print commands can send messages back to
 204 .B ippeveprinter
 205 on the standard error with one of the following prefixes:
 206 .TP 5
 207 \fBATTR: \fIattribute=value[ attribute=value]\fR
 208 Sets the named attribute(s) to the given values.
 209 Currently only the "job-impressions" and "job-impressions-completed" Job Status attributes and the "marker-xxx", "printer-alert", "printer-alert-description", "printer-supply", and "printer-supply-description" Printer Status attributes can be set.
 210 .TP 5
 211 \fBDEBUG: \fIDebugging message\fR
 212 Logs a debugging message if at least two \-v's have been specified.
 213 .TP 5
 214 \fBERROR: \fIError message\fR
 215 Logs an error message and copies the message to the "job-state-message" attribute.
 216 .TP 5
 217 \fBINFO: \fIInformational message\fR
 218 Logs an informational/progress message if \-v has been specified and copies the message to the "job-state-message" attribute unless an error has been reported.
 219 .TP 5
 220 \fBSTATE: \fIkeyword[,keyword,...]\fR
 221 Sets the printer's "printer-state-reasons" attribute to the listed keywords.
 222 .TP 5
 223 \fBSTATE: -\fIkeyword[,keyword,...]\fR
 224 Removes the listed keywords from the printer's "printer-state-reasons" attribute.
 225 .TP 5
 226 \fBSTATE: +\fIkeyword[,keyword,...]\fR
 227 Adds the listed keywords to the printer's "printer-state-reasons" attribute.
 228 .SH EXAMPLES
 229 Run
 230 .B ippeveprinter
 231 with a service name of My Cool Printer:
 232 .nf
 233
 234     ippeveprinter "My Cool Printer"
 235 .fi
 236 .LP
 237 Run the
 238 .BR file (1)
 239 command whenever a job is sent to the server:
 240 .nf
 241
 242     ippeveprinter \-c /usr/bin/file "My Cool Printer"
 243 .fi
 244 .SH SEE ALSO
 245 PWG Internet Printing Protocol Workgroup (http://www.pwg.org/ipp)
 246 .SH COPYRIGHT
 247 Copyright \[co] 2007-2019 by Apple Inc.