[thirdparty/cups.git] / doc / help / man-cupsd-logs.html

<!DOCTYPE HTML>
<html>
<!-- SECTION: Man Pages -->
<head>
	<link rel="stylesheet" type="text/css" href="../cups-printable.css">
	<title>cupsd-logs(5)</title>
</head>
<body>
<h1 class="title">cupsd-logs(5)</h1>
<h2 class="title"><a name="NAME">Name</a></h2>
cupsd-logs - cupsd log files (access_log, error_log, and page_log)
<h2 class="title"><a name="DESCRIPTION">Description</a></h2>
<b>cupsd</b>(8)
normally maintains three log files: <i>access_log</i> to track requests that are submitted to the scheduler, <i>error_log</i> to track progress and errors, and <i>page_log</i> to track pages that are printed.
Configuration directives in
<b>cupsd.conf</b>(5)
and
<b>cups-files.conf</b>(5)
control what information is logged and where it is stored.
<h3><a name="ACCESS_LOG_FILE_FORMAT">Access Log File Format</a></h3>
The <i>access_log</i> file lists each HTTP resource that is accessed by a web browser or client.
Each line is in an extended version of the so-called "Common Log Format" used by many web servers and web reporting tools:
<pre class="man">

    <i>host group user date-time </i>"<i>method resource version</i>" <i>status bytes
      ipp-operation ipp-status</i>

</pre>
For example:
<pre class="man">

    10.0.1.2 - - [01/Dec/2005:21:50:28 +0000] "POST / HTTP/1.1" 200 317
      CUPS-Get-Printers successful-ok-ignored-or-substituted-attributes
    localhost - - [01/Dec/2005:21:50:32 +0000] "GET /admin HTTP/1.1"
      200 0 - -
    localhost - - [01/Dec/2005:21:50:32 +0000] "POST / HTTP/1.1"
      200 157 CUPS-Get-Printers
      successful-ok-ignored-or-substituted-attributes
    localhost - - [01/Dec/2005:21:50:32 +0000] "POST / HTTP/1.1"
      200 1411 CUPS-Get-Devices -
    localhost - - [01/Dec/2005:21:50:32 +0000] "GET /admin HTTP/1.1"
      200 6667 - -

</pre>
The <i>host</i> field will normally only be an IP address unless you have enabled the HostNameLookups directive in the <i>cupsd.conf</i> file or if the IP address corresponds to your local machine.
<p>The <i>group</i> field always contains "-".
<p>The <i>user</i> field is the authenticated username of the requesting user.
If no username and password is supplied for the request then this field contains "-".
<p>The <i>date-time</i> field is the date and time of the request in local time and is in the format "[DD/MON/YYYY:HH:MM:SS +ZZZZ]".
<p>The <i>method</i> field is the HTTP method used: "GET", "HEAD", "OPTIONS", "POST", or "PUT".
"GET" requests are used to get files from the server, both for the web interface and to get configuration and log files.
"HEAD" requests are used to get information about a resource prior to a "GET".
"OPTIONS" requests are used to upgrade connections to TLS encryption.
"POST" requests are used for web interface forms and IPP requests.
"PUT" requests are used to upload configuration files.
<p>The <i>resource</i> field is the filename of the requested resource.
<p>The <i>version</i> field is the HTTP specification version used by the client.
For CUPS clients this will always be "HTTP/1.1".
<p>The <i>status</i> field contains the HTTP result status of the request, as follows:
<div style="margin-left: 5.0em;">
<dl class="man">
<dt>200
<dd style="margin-left: 5.0em">Successful operation.
<dt>201
<dd style="margin-left: 5.0em">File created/modified successfully.
<dt>304
<dd style="margin-left: 5.0em">The requested file has not changed.
<dt>400
<dd style="margin-left: 5.0em">Bad HTTP request; typically this means that you have a malicious program trying to access your server.
<dt>401
<dd style="margin-left: 5.0em">Unauthorized, authentication (username + password) is required.
<dt>403
<dd style="margin-left: 5.0em">Access is forbidden; typically this means that a client tried to access a file or resource they do not have permission to access.
<dt>404
<dd style="margin-left: 5.0em">The file or resource does not exist.
<dt>405
<dd style="margin-left: 5.0em">URL access method is not allowed; typically this means you have a web browser using your server as a proxy.
<dt>413
<dd style="margin-left: 5.0em">Request too large; typically this means that a client tried to print a file larger than the MaxRequestSize allows.
<dt>426
<dd style="margin-left: 5.0em">Upgrading to TLS-encrypted connection.
<dt>500
<dd style="margin-left: 5.0em">Server error; typically this happens when the server is unable to open/create a file - consult the error_log file for details.
<dt>501
<dd style="margin-left: 5.0em">The client requested encryption but encryption support is not enabled/compiled in.
<dt>505
<dd style="margin-left: 5.0em">HTTP version number not supported; typically this means that you have a malicious program trying to access your server.
</div>
</dl>
<p>The <i>bytes</i> field contains the number of bytes in the request.
For POST requests the bytes field contains the number of bytes of non-IPP data that is received from the client.
<p>The <i>ipp-operation</i> field contains either "-" for non-IPP requests or the IPP operation name for POST requests containing an IPP request.
<p>The <i>ipp-status</i> field contains either "-" for non-IPP requests or the IPP status code name for POST requests containing an IPP response.
<h3><a name="ERROR_LOG_FILE_FORMAT">Error Log File Format</a></h3>
The <i>error_log</i> file lists messages from the scheduler - errors, warnings, etc. The LogLevel directive in the
<b>cupsd.conf</b>(5)
file controls which messages are logged:
<pre class="man">

    level date-time message

</pre>
For example:
<pre class="man">

    I [20/May/1999:19:18:28 +0000] [Job 1] Queued on 'DeskJet' by 'mike'.
    D [20/May/1999:19:18:28 +0000] [Job 1] argv[0]="DeskJet"
    D [20/May/1999:19:18:28 +0000] [Job 1] argv[1]="1"
    D [20/May/1999:19:18:28 +0000] [Job 1] argv[2]="mike"
    D [20/May/1999:19:18:28 +0000] [Job 1] argv[3]="myjob"
    D [20/May/1999:19:18:28 +0000] [Job 1] argv[4]="1"
    D [20/May/1999:19:18:28 +0000] [Job 1] argv[5]="media=
      na_letter_8.5x11in sides=one-sided"
    D [20/May/1999:19:18:28 +0000] [Job 1] argv[6]="/var/spool/cups/
      d000001-001"
    I [20/May/1999:19:21:02 +0000] [Job 2] Queued on 'DeskJet' by 'mike'.
    I [20/May/1999:19:22:24 +0000] [Job 2] Canceled by 'mike'.

</pre>
The <i>level</i> field contains the type of message:
<dl class="man">
<dt>A
<dd style="margin-left: 5.0em">Alert message (LogLevel alert)
<dt>C
<dd style="margin-left: 5.0em">Critical error message (LogLevel crit)
<dt>D
<dd style="margin-left: 5.0em">Debugging message (LogLevel debug)
<dt>d
<dd style="margin-left: 5.0em">Detailed debugging message (LogLevel debug2)
<dt>E
<dd style="margin-left: 5.0em">Normal error message (LogLevel error)
<dt>I
<dd style="margin-left: 5.0em">Informational message (LogLevel info)
<dt>N
<dd style="margin-left: 5.0em">Notice message (LogLevel notice)
<dt>W
<dd style="margin-left: 5.0em">Warning message (LogLevel warn)
<dt>X
<dd style="margin-left: 5.0em">Emergency error message (LogLevel emerg)
</dl>
<p>The <i>date-time</i> 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 <i>access_log</i> file.
<p>The <i>message</i> field contains a free-form textual message.
Messages from job filters are prefixed with "[Job NNN]" where "NNN" is the job ID.
<h3><a name="PAGE_LOG_FILE_FORMAT">Page Log File Format</a></h3>
The <i>page_log</i> file lists the total number of pages (sheets) that are printed.
By default, each line contains the following information:
<pre class="man">

    <i>printer user job-id date-time </i><b>total </b><i>num-sheets job-billing
      job-originating-host-name job-name media sides</i>

</pre>
For example the entry for a two page job called "myjob" might look like:
<pre class="man">

    DeskJet root 1 [20/May/1999:19:21:06 +0000] total 2 acme-123
      localhost myjob na_letter_8.5x11in one-sided

</pre>
The PageLogFormat directive in the
<b>cupsd.conf</b>(5)
file can be used to change this information.
<p>The <i>printer</i> field contains the name of the printer that printed the page.
If you send a job to a printer class, this field will contain the name of the printer that was assigned the job.
<p>The <i>user</i> field contains the name of the user (the IPP requesting-user-name attribute) that submitted this file for printing.
<p>The <i>job-id</i> field contains the job number of the page being printed.
<p>The <i>date-time</i> 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 <i>access_log</i> file.
<p>The <i>num-sheets</i> field provides the total number of pages (sheets) that have been printed on for the job.
<p>The <i>job-billing</i> 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.
<p>The <i>job-originating-host-name</i> field contains the hostname or IP address of the client that printed the job.
<p>The <i>job-name</i> field contains a copy of the job-name attribute provided with the IPP Create-Job or Print-Job requests or "-" if none was provided.
<p>The <i>media</i> 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.
<p>The <i>sides</i> field contains a copy of the sides attribute provided with the IPP Create-Job or Print-Job requests or "-" if none was provided.
<h2 class="title"><a name="SEE_ALSO">See Also</a></h2>
<b>cupsd</b>(8),
<b>cupsd.conf</b>(5),
<b>cups-files.conf</b>(5),
CUPS Online Help (<a href="http://localhost:631/help">http://localhost:631/help</a>)
<h2 class="title"><a name="COPYRIGHT">Copyright</a></h2>
Copyright &copy; 2007-2019 by Apple Inc.

</body>
</html>
Commit	Line	Data
b960a3cf MS	1	<!DOCTYPE HTML>
	2	<html>
	3	<!-- SECTION: Man Pages -->
	4	<head>
	5	<link rel="stylesheet" type="text/css" href="../cups-printable.css">
	6	<title>cupsd-logs(5)</title>
	7	</head>
	8	<body>
	9	<h1 class="title">cupsd-logs(5)</h1>
	10	<h2 class="title"><a name="NAME">Name</a></h2>
	11	cupsd-logs - cupsd log files (access_log, error_log, and page_log)
	12	<h2 class="title"><a name="DESCRIPTION">Description</a></h2>
87030afb	13	<b>cupsd</b>(8)
b960a3cf MS	14	normally maintains three log files: <i>access_log</i> to track requests that are submitted to the scheduler, <i>error_log</i> to track progress and errors, and <i>page_log</i> to track pages that are printed.
b960a3cf MS	15	Configuration directives in
87030afb	16	<b>cupsd.conf</b>(5)
b960a3cf	17	and
87030afb	18	<b>cups-files.conf</b>(5)
b960a3cf MS	19	control what information is logged and where it is stored.
	20	<h3><a name="ACCESS_LOG_FILE_FORMAT">Access Log File Format</a></h3>
	21	The <i>access_log</i> file lists each HTTP resource that is accessed by a web browser or client.
	22	Each line is in an extended version of the so-called "Common Log Format" used by many web servers and web reporting tools:
	23	<pre class="man">
	24
	25	<i>host group user date-time </i>"<i>method resource version</i>" <i>status bytes
	26	ipp-operation ipp-status</i>
	27
	28	</pre>
	29	For example:
	30	<pre class="man">
	31
	32	10.0.1.2 - - [01/Dec/2005:21:50:28 +0000] "POST / HTTP/1.1" 200 317
	33	CUPS-Get-Printers successful-ok-ignored-or-substituted-attributes
	34	localhost - - [01/Dec/2005:21:50:32 +0000] "GET /admin HTTP/1.1"
	35	200 0 - -
	36	localhost - - [01/Dec/2005:21:50:32 +0000] "POST / HTTP/1.1"
	37	200 157 CUPS-Get-Printers
	38	successful-ok-ignored-or-substituted-attributes
	39	localhost - - [01/Dec/2005:21:50:32 +0000] "POST / HTTP/1.1"
	40	200 1411 CUPS-Get-Devices -
	41	localhost - - [01/Dec/2005:21:50:32 +0000] "GET /admin HTTP/1.1"
	42	200 6667 - -
	43
	44	</pre>
	45	The <i>host</i> field will normally only be an IP address unless you have enabled the HostNameLookups directive in the <i>cupsd.conf</i> file or if the IP address corresponds to your local machine.
	46	<p>The <i>group</i> field always contains "-".
	47	<p>The <i>user</i> field is the authenticated username of the requesting user.
	48	If no username and password is supplied for the request then this field contains "-".
	49	<p>The <i>date-time</i> field is the date and time of the request in local time and is in the format "[DD/MON/YYYY:HH:MM:SS +ZZZZ]".
	50	<p>The <i>method</i> field is the HTTP method used: "GET", "HEAD", "OPTIONS", "POST", or "PUT".
	51	"GET" requests are used to get files from the server, both for the web interface and to get configuration and log files.
	52	"HEAD" requests are used to get information about a resource prior to a "GET".
	53	"OPTIONS" requests are used to upgrade connections to TLS encryption.
	54	"POST" requests are used for web interface forms and IPP requests.
	55	"PUT" requests are used to upload configuration files.
	56	<p>The <i>resource</i> field is the filename of the requested resource.
	57	<p>The <i>version</i> field is the HTTP specification version used by the client.
	58	For CUPS clients this will always be "HTTP/1.1".
	59	<p>The <i>status</i> field contains the HTTP result status of the request, as follows:
	60	<div style="margin-left: 5.0em;">
	61	<dl class="man">
	62	<dt>200
	63	<dd style="margin-left: 5.0em">Successful operation.
	64	<dt>201
	65	<dd style="margin-left: 5.0em">File created/modified successfully.
	66	<dt>304
	67	<dd style="margin-left: 5.0em">The requested file has not changed.
	68	<dt>400
	69	<dd style="margin-left: 5.0em">Bad HTTP request; typically this means that you have a malicious program trying to access your server.
	70	<dt>401
	71	<dd style="margin-left: 5.0em">Unauthorized, authentication (username + password) is required.
	72	<dt>403
	73	<dd style="margin-left: 5.0em">Access is forbidden; typically this means that a client tried to access a file or resource they do not have permission to access.
	74	<dt>404
	75	<dd style="margin-left: 5.0em">The file or resource does not exist.
	76	<dt>405
	77	<dd style="margin-left: 5.0em">URL access method is not allowed; typically this means you have a web browser using your server as a proxy.
	78	<dt>413
	79	<dd style="margin-left: 5.0em">Request too large; typically this means that a client tried to print a file larger than the MaxRequestSize allows.
	80	<dt>426
	81	<dd style="margin-left: 5.0em">Upgrading to TLS-encrypted connection.
	82	<dt>500
83	<dd style="margin-left: 5.0em">Server error; typically this happens when the server is unable to open/create a file - consult the error_log file for details.
84	<dt>501
85	<dd style="margin-left: 5.0em">The client requested encryption but encryption support is not enabled/compiled in.
86	<dt>505
87	<dd style="margin-left: 5.0em">HTTP version number not supported; typically this means that you have a malicious program trying to access your server.
88	</div>
89	</dl>
90	<p>The <i>bytes</i> field contains the number of bytes in the request.
91	For POST requests the bytes field contains the number of bytes of non-IPP data that is received from the client.
92	<p>The <i>ipp-operation</i> field contains either "-" for non-IPP requests or the IPP operation name for POST requests containing an IPP request.
93	<p>The <i>ipp-status</i> field contains either "-" for non-IPP requests or the IPP status code name for POST requests containing an IPP response.
94	<h3><a name="ERROR_LOG_FILE_FORMAT">Error Log File Format</a></h3>
95	The <i>error_log</i> file lists messages from the scheduler - errors, warnings, etc. The LogLevel directive in the
87030afb	96	<b>cupsd.conf</b>(5)
b960a3cf MS	97	file controls which messages are logged:
	98	<pre class="man">
	99
	100	level date-time message
	101
	102	</pre>
	103	For example:
	104	<pre class="man">
	105
	106	I [20/May/1999:19:18:28 +0000] [Job 1] Queued on 'DeskJet' by 'mike'.
	107	D [20/May/1999:19:18:28 +0000] [Job 1] argv[0]="DeskJet"
	108	D [20/May/1999:19:18:28 +0000] [Job 1] argv[1]="1"
	109	D [20/May/1999:19:18:28 +0000] [Job 1] argv[2]="mike"
	110	D [20/May/1999:19:18:28 +0000] [Job 1] argv[3]="myjob"
	111	D [20/May/1999:19:18:28 +0000] [Job 1] argv[4]="1"
	112	D [20/May/1999:19:18:28 +0000] [Job 1] argv[5]="media=
	113	na_letter_8.5x11in sides=one-sided"
	114	D [20/May/1999:19:18:28 +0000] [Job 1] argv[6]="/var/spool/cups/
	115	d000001-001"
	116	I [20/May/1999:19:21:02 +0000] [Job 2] Queued on 'DeskJet' by 'mike'.
	117	I [20/May/1999:19:22:24 +0000] [Job 2] Canceled by 'mike'.
	118
	119	</pre>
	120	The <i>level</i> field contains the type of message:
	121	<dl class="man">
	122	<dt>A
	123	<dd style="margin-left: 5.0em">Alert message (LogLevel alert)
	124	<dt>C
	125	<dd style="margin-left: 5.0em">Critical error message (LogLevel crit)
	126	<dt>D
	127	<dd style="margin-left: 5.0em">Debugging message (LogLevel debug)
	128	<dt>d
	129	<dd style="margin-left: 5.0em">Detailed debugging message (LogLevel debug2)
	130	<dt>E
	131	<dd style="margin-left: 5.0em">Normal error message (LogLevel error)
	132	<dt>I
	133	<dd style="margin-left: 5.0em">Informational message (LogLevel info)
	134	<dt>N
	135	<dd style="margin-left: 5.0em">Notice message (LogLevel notice)
	136	<dt>W
	137	<dd style="margin-left: 5.0em">Warning message (LogLevel warn)
	138	<dt>X
	139	<dd style="margin-left: 5.0em">Emergency error message (LogLevel emerg)
	140	</dl>
	141	<p>The <i>date-time</i> 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 <i>access_log</i> file.
	142	<p>The <i>message</i> field contains a free-form textual message.
	143	Messages from job filters are prefixed with "[Job NNN]" where "NNN" is the job ID.
	144	<h3><a name="PAGE_LOG_FILE_FORMAT">Page Log File Format</a></h3>
dda99de9	145	The <i>page_log</i> file lists the total number of pages (sheets) that are printed.
b960a3cf MS	146	By default, each line contains the following information:
	147	<pre class="man">
	148
dda99de9	149	<i>printer user job-id date-time </i><b>total </b><i>num-sheets job-billing
b960a3cf MS	150	job-originating-host-name job-name media sides</i>
	151
	152	</pre>
dda99de9	153	For example the entry for a two page job called "myjob" might look like:
b960a3cf MS	154	<pre class="man">
b960a3cf MS	155
b960a3cf MS	156	DeskJet root 1 [20/May/1999:19:21:06 +0000] total 2 acme-123
	157	localhost myjob na_letter_8.5x11in one-sided
	158
	159	</pre>
	160	The PageLogFormat directive in the
87030afb	161	<b>cupsd.conf</b>(5)
b960a3cf MS	162	file can be used to change this information.
	163	<p>The <i>printer</i> field contains the name of the printer that printed the page.
	164	If you send a job to a printer class, this field will contain the name of the printer that was assigned the job.
	165	<p>The <i>user</i> field contains the name of the user (the IPP requesting-user-name attribute) that submitted this file for printing.
	166	<p>The <i>job-id</i> field contains the job number of the page being printed.
	167	<p>The <i>date-time</i> field contains the date and time of when the page started printing.
	168	The format of this field is identical to the data-time field in the <i>access_log</i> file.
dda99de9	169	<p>The <i>num-sheets</i> field provides the total number of pages (sheets) that have been printed on for the job.
b960a3cf MS	170	<p>The <i>job-billing</i> 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.
	171	<p>The <i>job-originating-host-name</i> field contains the hostname or IP address of the client that printed the job.
	172	<p>The <i>job-name</i> field contains a copy of the job-name attribute provided with the IPP Create-Job or Print-Job requests or "-" if none was provided.
	173	<p>The <i>media</i> 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.
	174	<p>The <i>sides</i> field contains a copy of the sides attribute provided with the IPP Create-Job or Print-Job requests or "-" if none was provided.
	175	<h2 class="title"><a name="SEE_ALSO">See Also</a></h2>
87030afb MS	176	<b>cupsd</b>(8),
	177	<b>cupsd.conf</b>(5),
	178	<b>cups-files.conf</b>(5),
b960a3cf MS	179	CUPS Online Help (<a href="http://localhost:631/help">http://localhost:631/help</a>)
b960a3cf MS	180	<h2 class="title"><a name="COPYRIGHT">Copyright</a></h2>
87030afb	181	Copyright © 2007-2019 by Apple Inc.
b960a3cf MS	182
	183	</body>
	184	</html>