man/cupsd-logs.man

   1 .\"
   2 .\" "$Id$"
   3 .\"
   4 .\" cupsd-logs man page for CUPS.
   5 .\"
   6 .\" Copyright 2007-2014 by Apple Inc.
   7 .\" Copyright 1997-2006 by Easy Software Products.
   8 .\"
   9 .\" These coded instructions, statements, and computer programs are the
  10 .\" property of Apple Inc. and are protected by Federal copyright
  11 .\" law.  Distribution and use rights are outlined in the file "LICENSE.txt"
  12 .\" which should have been included with this file.  If this file is
  13 .\" file is missing or damaged, see the license at "http://www.cups.org/".
  14 .\"
  15 .TH cupsd-logs 5 "CUPS" "11 June 2014" "Apple Inc."
  16 .SH NAME
  17 cupsd\-logs \- cupsd log files (access_log, error_log, and page_log)
  18 .SH DESCRIPTION
  19 .BR cupsd (8)
  20 normally maintains three log files: \fIaccess_log\fR to track requests that are submitted to the scheduler, \fIerror_log\fR to track progress and errors, and \fIpage_log\fR to track pages that are printed.
  21 Configuration directives in
  22 .BR cupsd.conf (5)
  23 and
  24 .BR cups-files.conf (5)
  25 control what information is logged and where it is stored.
  26 .SS ACCESS LOG FILE FORMAT
  27 The \fIaccess_log\fR file lists each HTTP resource that is accessed by a web browser or client.
  28 Each line is in an extended version of the so-called "Common Log Format" used by many web servers and web reporting tools:
  29 .nf
  30
  31     \fIhost group user date-time \fR"\fImethod resource version\fR" \fIstatus bytes
  32       ipp-operation ipp-status\fR
  33
  34 .fi
  35 For example:
  36 .nf
  37
  38     10.0.1.2 - - [01/Dec/2005:21:50:28 +0000] "POST / HTTP/1.1" 200 317
  39       CUPS-Get-Printers successful-ok-ignored-or-substituted-attributes
  40     localhost - - [01/Dec/2005:21:50:32 +0000] "GET /admin HTTP/1.1"
  41       200 0 - -
  42     localhost - - [01/Dec/2005:21:50:32 +0000] "POST / HTTP/1.1"
  43       200 157 CUPS-Get-Printers
  44       successful-ok-ignored-or-substituted-attributes
  45     localhost - - [01/Dec/2005:21:50:32 +0000] "POST / HTTP/1.1"
  46       200 1411 CUPS-Get-Devices -
  47     localhost - - [01/Dec/2005:21:50:32 +0000] "GET /admin HTTP/1.1"
  48       200 6667 - -
  49
  50 .fi
  51 The \fIhost\fR field will normally only be an IP address unless you have enabled the HostNameLookups directive in the \fIcupsd.conf\fR file or if the IP address corresponds to your local machine.
  52 .LP
  53 The \fIgroup\fR field always contains "-".
  54 .LP
  55 The \fIuser\fR field is the authenticated username of the requesting user.
  56 If no username and password is supplied for the request then this field contains "-".
  57 .LP
  58 The \fIdate-time\fR field is the date and time of the request in local time and is in the format "[DD/MON/YYYY:HH:MM:SS +ZZZZ]".
  59 .LP
  60 The \fImethod\fR field is the HTTP method used: "GET", "HEAD", "OPTIONS", "POST", or "PUT".
  61 "GET" requests are used to get files from the server, both for the web interface and to get configuration and log files.
  62 "HEAD" requests are used to get information about a resource prior to a "GET".
  63 "OPTIONS" requests are used to upgrade connections to TLS encryption.
  64 "POST" requests are used for web interface forms and IPP requests.
  65 "PUT" requests are used to upload configuration files.
  66 .LP
  67 The \fIresource\fR field is the filename of the requested resource.
  68 .LP
  69 The \fIversion\fR field is the HTTP specification version used by the client.
  70 For CUPS clients this will always be "HTTP/1.1".
  71 .LP
  72 The \fIstatus\fR field contains the HTTP result status of the request, as follows:
  73 .RS 5
  74 .TP 5
  75 200
  76 Successful operation.
  77 .TP 5
  78 201
  79 File created/modified successfully.
  80 .TP 5
  81 304
  82 The requested file has not changed.
  83 .TP 5
  84 400
  85 Bad HTTP request; typically this means that you have a malicious program trying to access your server.
  86 .TP 5
  87 401
  88 Unauthorized, authentication (username + password) is required.
  89 .TP 5
  90 403
  91 Access is forbidden; typically this means that a client tried to access a file or resource they do not have permission to access.
  92 .TP 5
  93 404
  94 The file or resource does not exist.
  95 .TP 5
  96 405
  97 URL access method is not allowed; typically this means you have a web browser using your server as a proxy.
  98 .TP 5
  99 413
 100 Request too large; typically this means that a client tried to print a file larger than the MaxRequestSize allows.
 101 .TP 5
 102 426
 103 Upgrading to TLS-encrypted connection.
 104 .TP 5
 105 500
 106 Server error; typically this happens when the server is unable to open/create a file - consult the error_log file for details.
 107 .TP 5
 108 501
 109 The client requested encryption but encryption support is not enabled/compiled in.
 110 .TP 5
 111 505
 112 HTTP version number not supported; typically this means that you have a malicious program trying to access your server.
 113 .RE
 114 .LP
 115 The \fIbytes\fR field contains the number of bytes in the request.
 116 For POST requests the bytes field contains the number of bytes of non-IPP data that is received from the client.
 117 .LP
 118 The \fIipp-operation\fR field contains either "-" for non-IPP requests or the IPP operation name for POST requests containing an IPP request.
 119 .LP
 120 The \fIipp-status\fR field contains either "-" for non-IPP requests or the IPP status code name for POST requests containing an IPP response.
 121 .SS ERROR LOG FILE FORMAT
 122 The \fIerror_log\fR file lists messages from the scheduler - errors, warnings, etc. The LogLevel directive in the
 123 .BR cupsd.conf (5)
 124 file controls which messages are logged:
 125 .nf
 126
 127     level date-time message
 128
 129 .fi
 130 For example:
 131 .nf
 132
 133     I [20/May/1999:19:18:28 +0000] [Job 1] Queued on 'DeskJet' by 'mike'.
 134     D [20/May/1999:19:18:28 +0000] [Job 1] argv[0]="DeskJet"
 135     D [20/May/1999:19:18:28 +0000] [Job 1] argv[1]="1"
 136     D [20/May/1999:19:18:28 +0000] [Job 1] argv[2]="mike"
 137     D [20/May/1999:19:18:28 +0000] [Job 1] argv[3]="myjob"
 138     D [20/May/1999:19:18:28 +0000] [Job 1] argv[4]="1"
 139     D [20/May/1999:19:18:28 +0000] [Job 1] argv[5]="media=
 140       na_letter_8.5x11in sides=one-sided"
 141     D [20/May/1999:19:18:28 +0000] [Job 1] argv[6]="/var/spool/cups/
 142       d000001-001"
 143     I [20/May/1999:19:21:02 +0000] [Job 2] Queued on 'DeskJet' by 'mike'.
 144     I [20/May/1999:19:22:24 +0000] [Job 2] Canceled by 'mike'.
 145
 146 .fi
 147 The \fIlevel\fR field contains the type of message:
 148 .TP 5
 149 A
 150 Alert message (LogLevel alert)
 151 .TP 5
 152 C
 153 Critical error message (LogLevel crit)
 154 .TP 5
 155 D
 156 Debugging message (LogLevel debug)
 157 .TP 5
 158 d
 159 Detailed debugging message (LogLevel debug2)
 160 .TP 5
 161 E
 162 Normal error message (LogLevel error)
 163 .TP 5
 164 I
 165 Informational message (LogLevel info)
 166 .TP 5
 167 N
 168 Notice message (LogLevel notice)
 169 .TP 5
 170 W
 171 Warning message (LogLevel warn)
 172 .TP 5
 173 X
 174 Emergency error message (LogLevel emerg)
 175 .LP
 176 The \fIdate-time\fR field contains the date and time of when the page started printing. The format of this field is identical to the data-time field in the \fIaccess_log\fR file.
 177 .LP
 178 The \fImessage\fR field contains a free-form textual message.
 179 Messages from job filters are prefixed with "[Job NNN]" where "NNN" is the job ID.
 180 .SS PAGE LOG FILE FORMAT
 181 The \fIpage_log\fR file lists each page or group of pages that are sent to a printer.
 182 By default, each line contains the following information:
 183 .nf
 184
 185     \fIprinter user job-id date-time page-number num-copies job-billing
 186       job-originating-host-name job-name media sides\fR
 187
 188     \fIprinter user job-id date-time \fBtotal \fInum-impressions job-billing
 189       job-originating-host-name job-name media sides\fR
 190
 191 .fi
 192 For example the entries for a two page job called "myjob" might look like:
 193 .nf
 194
 195     DeskJet root 1 [20/May/1999:19:21:05 +0000] 1 1 acme-123
 196       localhost myjob na_letter_8.5x11in one-sided
 197     DeskJet root 1 [20/May/1999:19:21:05 +0000] 2 1 acme-123
 198       localhost myjob na_letter_8.5x11in one-sided
 199
 200     DeskJet root 1 [20/May/1999:19:21:06 +0000] total 2 acme-123
 201       localhost myjob na_letter_8.5x11in one-sided
 202
 203 .fi
 204 The PageLogFormat directive in the
 205 .BR cupsd.conf (5)
 206 file can be used to change this information.
 207 .LP
 208 The \fIprinter\fR field contains the name of the printer that printed the page.
 209 If you send a job to a printer class, this field will contain the name of the printer that was assigned the job.
 210 .LP
 211 The \fIuser\fR field contains the name of the user (the IPP requesting-user-name attribute) that submitted this file for printing.
 212 .LP
 213 The \fIjob-id\fR field contains the job number of the page being printed.
 214 .LP
 215 The \fIdate-time\fR field contains the date and time of when the page started printing.
 216 The format of this field is identical to the data-time field in the \fIaccess_log\fR file.
 217 .LP
 218 The \fIpage-number\fR and \fInum-copies\fR fields contain the page number and number of copies being printed of that page.
 219 For printers that cannot produce copies on their own, the num-copies field will always be 1.
 220 .LP
 221 Lines containing the keyword "total" have a \fInum-impressions\fR field instead which provides the total number of impressions (sides) that have been printed on for the job.
 222 .LP
 223 The \fIjob-billing\fR field contains a copy of the job-billing or job-account-id attributes provided with the IPP Create-Job or Print-Job requests or "-" if neither was provided.
 224 .LP
 225 The \fIjob-originating-host-name\fR field contains the hostname or IP address of the client that printed the job.
 226 .LP
 227 The \fIjob-name\fR field contains a copy of the job-name attribute provided with the IPP Create-Job or Print-Job requests or "-" if none was provided.
 228 .LP
 229 The \fImedia\fR field contains a copy of the media or media-col/media-size attribute provided with the IPP Create-Job or Print-Job requests or "-" if none was provided.
 230 .LP
 231 The \fIsides\fR field contains a copy of the sides attribute provided with the IPP Create-Job or Print-Job requests or "-" if none was provided.
 232 .SH SEE ALSO
 233 .BR cupsd (8),
 234 .BR cupsd.conf (5),
 235 .BR cups-files.conf (5),
 236 CUPS Online Help (http://localhost:631/help)
 237 .SH COPYRIGHT
 238 Copyright \[co] 2007-2015 by Apple Inc.
 239 .\"
 240 .\" End of "$Id$".
 241 .\"