source: trunk/third/lprng/doc/LPRng-HOWTO-17.html @ 13098

Revision 13098, 12.2 KB checked in by danw, 25 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r13097, which included commits to RCS files with non-trunk default branches.
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2<HTML>
3<HEAD>
4 <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
5 <TITLE> LPRng-HOWTO: Status Monitoring and Logging</TITLE>
6 <LINK HREF="LPRng-HOWTO-18.html" REL=next>
7 <LINK HREF="LPRng-HOWTO-16.html" REL=previous>
8 <LINK HREF="LPRng-HOWTO.html#toc17" REL=contents>
9</HEAD>
10<BODY>
11<A HREF="LPRng-HOWTO-18.html">Next</A>
12<A HREF="LPRng-HOWTO-16.html">Previous</A>
13<A HREF="LPRng-HOWTO.html#toc17">Contents</A>
14<HR>
15<H2><A NAME="stalledtime"></A> <A NAME="statusref"></A> <A NAME="s17">17. Status Monitoring and Logging</A></H2>
16
17<P>Options used:
18<UL>
19<LI><CODE>stalled_time#</CODE><EM>time after which to report a stalled active job</EM></LI>
20</UL>
21<P>The most commonly used tool for LPRng status is LPQ.
22However,
23the LPC command can be used,
24and you can also get real time logging of status to a remote host.
25<P>
26<H2><A NAME="ss17.1">17.1 LPQ status reporting</A>
27</H2>
28
29<P>The LPQ status display produced by LPRng has three formats.
30<H2><A NAME="ss17.2">17.2 LPQ Short Format (lpq -s)</A>
31</H2>
32
33<P>This is one line per spool queue:
34<BLOCKQUOTE><CODE>
35<PRE>
36% lpq -sa
37t1@astart110  (printing disabled) 1 job
38t2@astart110  (routed/bounce to t1@astart110.astart.com) 0 jobs
39t3@astart110  (forwarding to t3a@astart110.astart.com)
40t3a@astart110  (forwarding to t2@astart110.astart.com)
41t4@astart110  (subservers t5, t6)  0 jobs
42t5@astart110  (serving t4) 0 jobs
43t6@astart110  (serving t4) 0 jobs
44</PRE>
45</CODE></BLOCKQUOTE>
46<P>Note that the name of the printer/host is first,
47followed by optional status information, followed by
48the number of jobs.  Only printcap entries with
49spool queues have a jobs word in the last position.
50The
51<CODE>-a</CODE> option forces status for all queues or the
52queues in the <CODE>all</CODE> printcap entry to be returned.
53<P>The <CODE>stalled_time</CODE> (default 120 seconds) printcap option can be used to set a
54time after which active jobs will be reported as stalled.
55<H2><A NAME="ss17.3">17.3 LPQ Long Format (lpq default, lpq -l, lpq -L)</A>
56</H2>
57
58<P>This is the default status display.
59It is a nicely formatted, extremely verbose format
60that is suitable for humble human interpretation. For example:
61<BLOCKQUOTE><CODE>
62<PRE>
63% lpq -a
64Printer: t1@astart110  'Test Printer 1' (printing disabled)
65 Queue: 1 printable job
66 Server: no server active
67 Status: finished operations at 09:44:00
68 Rank   Owner/ID                   Class Job  Files               Size Time   
691       papowell@astart110+202228663    A 10663 /tmp/hi               3 20:22:29
70Printer: t2@astart110  'Test Printer 2' (routed/bounce to t1@astart110.astart.com)
71 Queue: no printable jobs in queue
72 Status: finished operations at 16:30:08
73Printer: t3@astart110  (forwarding to t3a@astart110.astart.com)
74Printer: t3a@astart110  (forwarding to t2@astart110.astart.com)
75Printer: t4@astart110  (subservers t5, t6)
76 Queue: no printable jobs in queue
77 Status: finished operations at 09:44:06
78Server Printer: t5@astart110  (serving t4)
79 Queue: no printable jobs in queue
80 Status: finished operations at 09:44:06
81Server Printer: t6@astart110  (serving t4)
82 Queue: no printable jobs in queue
83 Status: finished operations at 09:10:00
84</PRE>
85</CODE></BLOCKQUOTE>
86<P>The <CODE>lpq -l</CODE> (longer information)
87option causes more of the status information to be printed.
88You can use increasing numbers of <CODE>lpq -l</CODE> options
89(<CODE> lpq -ll</CODE> also works) to get more status.
90Use <CODE> lpq -L</CODE> for the maximum amount of status information.
91<H2><A NAME="ss17.4">17.4 LPQ Verbose Format (lpq -v)</A>
92</H2>
93
94<P>This uses an extension to the RFC1179 protocol,
95and is supported only by LPRng.
96The amount of information displayed is the brutal,
97and in effect does a total database dump
98of the LPD.
99This has been developed in order to provide diagnostic
100and status information for databases that need to keep track of
101job progress through a spool queue.
102<BLOCKQUOTE><CODE>
103<PRE>
104% lpq -v
105Printer: t1@astart110
106 Comment: Test Printer 1
107 Printing: no
108 Spooling: yes
109 Queue: 1 printable job
110 Server: no server active
111 Status: accounting at end 'papowell@astart110+094352860' at 09:44:00
112 Status: printing 'papowell@astart110+094352860', closing device at 09:44:00
113 Status: printing 'papowell@astart110+094352860', finished  at 09:44:00
114 Status: subserver status 'JSUCC' for 'papowell@astart110+094352860' \
115            on attempt 1 at 09:44:00
116 Status: finished operations at 09:44:00
117 Job: papowell@astart110+202228663 status= 1
118 Job: papowell@astart110+202228663 CONTROL=
119 - Hastart110.astart.com
120 - Ppapowell
121 - J/tmp/hi
122 - CA
123 - Lpapowell
124 - Apapowell@astart110+202228663
125 - Qt1
126 - fdfA010663astart110.astart.com
127 - N/tmp/hi
128 - UdfA010663astart110.astart.com
129 Job: papowell@astart110+202228663 HOLDFILE=
130 - active 0
131 - done 0
132 - hold 0
133 - move 0
134....
135</PRE>
136</CODE></BLOCKQUOTE>
137<H2><A NAME="ss17.5">17.5 lpc status</A>
138</H2>
139
140<P>The LPC status command is used to show the status of the queues
141currently being managed by the LPRng server.
142Note that this form of the command is supported only by LPRng,
143and is not backwards compatible with BSD LPR implementations.
144<BLOCKQUOTE><CODE>
145<PRE>
146%lpc status all
147 Printer           Printing Spooling Jobs  Server   Slave Redirect Status/Debug
148lw4@astart4         enabled  enabled    0    none    none
149lw5@astart4         enabled  enabled    0    none    none
150</PRE>
151</CODE></BLOCKQUOTE>
152<P>The status display has a heading line and summary of the server status.
153<H2><A NAME="ss17.6">17.6 Remote Logger Operation</A>
154</H2>
155
156<P>Several sites have wanted a way to provide central logging of job
157status and/or information.  In order to do this,  the following functionality
158is provided with LPRng.
159<H3><A NAME="loggermaxsize"></A> <A NAME="loggertimeout"></A> <A NAME="loggerpathname"></A> <A NAME="loggerdestination"></A> Logger Network Communication</H3>
160
161<P>Options used:
162<UL>
163<LI><CODE>logger_destination=</CODE><EM>logger information destination</EM></LI>
164<LI><CODE>logger_pathname=</CODE><EM>pathname of temp file for log information</EM></LI>
165<LI><CODE>logger_max_size=</CODE><EM>max size in K of temp file for log information</EM></LI>
166<LI><CODE>logger_timeout=</CODE><EM>time between connection attempts</EM></LI>
167</UL>
168<P>The printcap/configuration variable <CODE>logger_destination</CODE> specifies
169a destination in the standard
170<CODE>host%port</CODE>
171notation used by LPRng.
172Host is the destination host, and can be a name or IP address.
173Port is the port on the destination host.
174A TCP/IP connection is made to the indicated port.
175<P>Log information is save in a temporary file specified by
176<CODE>logger_path</CODE>,
177and up to
178<CODE>logger_max_size</CODE>  K bytes of data will be saved.
179<P>If a connection cannot be made to the
180<CODE>logger_destination</CODE>,
181then every
182<CODE>logger_timeout</CODE> seconds a new connection attempt will be made.
183If <CODE>logger_timeout</CODE> is 0,
184then a connection attempt will be made every time new data arrives to be logged.
185<H3>Logger Messages</H3>
186
187<P>Log messages consist of a single line
188terminated with a newline (<CODE>\n</CODE>) character.
189<P>Each log message reports a system event or status change of the
190LPD server.
191When the connection is first established,
192a complete dump of the status of the LPD server is sent.
193After this,
194only status update messages are sent.
195The remote monitor can force a status dump by simply closing and
196reopening the connection.
197<H3>Message Format</H3>
198
199<P>Each message is encoded as a URI escaped string.
200That is, non-alphanumeric characters are encoded as the 3 character
201sequence <CODE>%xx</CODE>,  where <CODE>xx</CODE> is the hexadecimal value of the character.
202The message has the format <CODE>key=value</CODE>,
203where <CODE>key</CODE> indicates the message type.
204For example:
205<BLOCKQUOTE><CODE>
206<PRE>
207dump=host=astart4.astart.com%0aprinter=t1%0aprocess=1613%0aupdate_time=1999-03-2
208  3-20:32:17.148%0avalue=queue=holdall 0%25250aprinting_aborted=0x0%25250aprinting
209  _disabled=0x0%25250aspooling_disabled=0x0%25250a%250a%0a
210</PRE>
211</CODE></BLOCKQUOTE>
212<P>The following keys are used:
213<OL>
214<LI>dump<BR>
215A status dump of the current contents of a print queue.</LI>
216</OL>
217<P>Each message has a set of headers and a value.
218For example,
219the decoded dump message from the previous section would be:
220<BLOCKQUOTE><CODE>
221<PRE>
222host=astart4.astart.com
223printer=t1
224process=1613
225update_time=1999-03-23-20:32:17.148
226value=queue=holdall 0%250aprinting_aborted=0x0%250aprinting_disabled=0x0%250aspo
227  oling_disabled=0x0%250a%0a
228</PRE>
229</CODE></BLOCKQUOTE>
230<P>Each line consists of a key and a value.
231The
232<CODE>host</CODE> key indicates the host name,
233<CODE>printer</CODE> is the print queue,
234<CODE>process</CODE> is the process which generated the report or action,
235<CODE>update_time</CODE> is the time at which the report was generated,
236and
237<CODE>value</CODE> is the value of the report.
238<P>The decoded <CODE>value</CODE> of the above report is:
239<BLOCKQUOTE><CODE>
240<PRE>
241queue='holdall 0%0aprinting_aborted=0x0%0aprinting_disabled=0x0%0aspooling_dis
242  abled=0x0%0a
243</PRE>
244</CODE></BLOCKQUOTE>
245<P>The <CODE>queue</CODE> key provides the current value of the queue control file.
246<H3>Dump Messages</H3>
247
248<P>Dump messages are generated at the start of operations,
249and consist of a list of queue status messages.
250<H3>LPD Messages</H3>
251
252<P>These are used to indicate LPD startup or change in operation.
253<BLOCKQUOTE><CODE>
254<PRE>
255Decode: lpd=host=astart4.astart.com%0aprocess=1672%0aupdate_time=1999-03-23-20:5
2561:10.507%0avalue=Starting%0a
257host=astart4.astart.com
258process=1672
259update_time=1999-03-23-20:51:10.507
260value=Starting
261lpd: 'Starting'
262</PRE>
263</CODE></BLOCKQUOTE>
264<H3>Job Status Messages - UPDATE</H3>
265
266<P>Update messages are used to report changes in the queue contents,
267such as job arrival.
268<BLOCKQUOTE><CODE>
269<PRE>
270Decode: update=host=astart4.astart.com%0aidentifier=papowell@astart4+676%0anumbe
271 ...
272host=astart4.astart.com
273identifier=papowell@astart4+676
274number=676
275printer=t1
276process=1677
277update_time=1999-03-23-20:51:17.197
278value=bnrname=papowell%0acf_esc_image=Apapowell@astart4+676%250aCA%250aD1999-03-
279  ...
280</PRE>
281</CODE></BLOCKQUOTE>
282<P>This update message reports the arrival of a new job at the queue.
283The <CODE>value</CODE> field reports the control file contents:
284<BLOCKQUOTE><CODE>
285<PRE>
286cf_esc_image=Apapowell@astart4+676%0aCA%0aD1999-03-23-20:51:17.151%0aHastart4.as
287   tart.com%0aJ/tmp/hi%0aLpapowell%0aPpapowell%0aQt1%0aN/tmp/hi%0afdfA676astart4.as
288   tart.com%0aUdfA676astart4.astart.com%0a
289class=A
290date=1999-03-23-20:51:17.151
291file_hostname=astart4.astart.com
292fromhost=astart4.astart.com
293held=0x0
294hf_name=/var/tmp/LPD/t1/hfA676
295hold_class=0x0
296hold_time=0x0
297identifier=papowell@astart4+676
298job_time=0x36f86f45
299jobname=/tmp/hi
300logname=papowell
301number=676
302priority=A
303queuename=t1
304size=3
305transfername=cfA676astart4.astart.com
306update_time=1999-03-23-20:51:17.187
307</PRE>
308</CODE></BLOCKQUOTE>
309<P>The <CODE>update_time</CODE> field in the section above is the time that the
310job information was last updated.
311The <CODE>cf_esc_image</CODE> value is the URL escaped control file information.
312<H3>Printer Status Messages - PRSTATUS </H3>
313
314<P>These messages report printing or other activity related to a job.
315<BLOCKQUOTE><CODE>
316<PRE>
317Decode: prstatus=host=astart4.astart.com%0aidentifier=papowell@astart4+676%0anum
318ber=676%0aprinter=t1%0aprocess=1692%0aupdate_time=1999-03-23-21:02:04.855%0avalu
319e=finished 'papowell@astart4+676'%252c status 'JSUCC'%0a
320
321host=astart4.astart.com
322identifier=papowell@astart4+676
323number=676
324printer=t1
325process=1692
326update_time=1999-03-23-21:02:04.855
327value=finished 'papowell@astart4+676'%2c status 'JSUCC'
328PRSTATUS: 'finished 'papowell@astart4+676', status 'JSUCC''
329</PRE>
330</CODE></BLOCKQUOTE>
331<H2><A NAME="mail"></A> <A NAME="allowuserlogging"></A> <A NAME="ss17.7">17.7 LPR -mhost%port and user logging support</A>
332</H2>
333
334<P>The <CODE>lpr -m</CODE> option is used to request that <CODE>lpd</CODE>
335send mail to the user when a job has completed.
336LPRng extends this to allow mail addresses of the form
337<CODE> host[%port][/(TCP|UPD)]</CODE> to request that logging information
338be sent to the user as well.
339<P>The administrator should be aware that this is a possible security loophole,
340and that the
341<CODE>allow_user_logging</CODE>
342flag must be enabled to
343allow this operation.
344<HR>
345<A HREF="LPRng-HOWTO-18.html">Next</A>
346<A HREF="LPRng-HOWTO-16.html">Previous</A>
347<A HREF="LPRng-HOWTO.html#toc17">Contents</A>
348</BODY>
349</HTML>
Note: See TracBrowser for help on using the repository browser.