LPRng-HOWTO: Status Monitoring and Logging

Next Previous Contents

## 17. Status Monitoring and Logging

Options used:

- `stalled_time#`time after which to report a stalled active job

The most commonly used tool for LPRng status is LPQ. However, the LPC command can be used, and you can also get real time logging of status to a remote host.

## 17.1 LPQ status reporting

The LPQ status display produced by LPRng has three formats.

## 17.2 LPQ Short Format (lpq -s)

This is one line per spool queue:

> `

>     % lpq -sa
>     t1@astart110  (printing disabled) 1 job
>     t2@astart110  (routed/bounce to t1@astart110.astart.com) 0 jobs
>     t3@astart110  (forwarding to t3a@astart110.astart.com)
>     t3a@astart110  (forwarding to t2@astart110.astart.com)
>     t4@astart110  (subservers t5, t6)  0 jobs
>     t5@astart110  (serving t4) 0 jobs
>     t6@astart110  (serving t4) 0 jobs

> `

Note that the name of the printer/host is first, followed by optional status information, followed by the number of jobs. Only printcap entries with spool queues have a jobs word in the last position. The `-a` option forces status for all queues or the queues in the `all` printcap entry to be returned.

The `stalled_time` (default 120 seconds) printcap option can be used to set a time after which active jobs will be reported as stalled.

## 17.3 LPQ Long Format (lpq default, lpq -l, lpq -L)

This is the default status display. It is a nicely formatted, extremely verbose format that is suitable for humble human interpretation. For example:

> `

>     % lpq -a
>     Printer: t1@astart110  'Test Printer 1' (printing disabled)
>      Queue: 1 printable job
>      Server: no server active
>      Status: finished operations at 09:44:00
>      Rank   Owner/ID                   Class Job  Files               Size Time
>     1       papowell@astart110+202228663    A 10663 /tmp/hi               3 20:22:29
>     Printer: t2@astart110  'Test Printer 2' (routed/bounce to t1@astart110.astart.com)
>      Queue: no printable jobs in queue
>      Status: finished operations at 16:30:08
>     Printer: t3@astart110  (forwarding to t3a@astart110.astart.com)
>     Printer: t3a@astart110  (forwarding to t2@astart110.astart.com)
>     Printer: t4@astart110  (subservers t5, t6)
>      Queue: no printable jobs in queue
>      Status: finished operations at 09:44:06
>     Server Printer: t5@astart110  (serving t4)
>      Queue: no printable jobs in queue
>      Status: finished operations at 09:44:06
>     Server Printer: t6@astart110  (serving t4)
>      Queue: no printable jobs in queue
>      Status: finished operations at 09:10:00

> `

The `lpq -l` (longer information) option causes more of the status information to be printed. You can use increasing numbers of `lpq -l` options (`lpq -ll` also works) to get more status. Use `lpq -L` for the maximum amount of status information.

## 17.4 LPQ Verbose Format (lpq -v)

This uses an extension to the RFC1179 protocol, and is supported only by LPRng. The amount of information displayed is the brutal, and in effect does a total database dump of the LPD. This has been developed in order to provide diagnostic and status information for databases that need to keep track of job progress through a spool queue.

> `

>     % lpq -v
>     Printer: t1@astart110
>      Comment: Test Printer 1
>      Printing: no
>      Spooling: yes
>      Queue: 1 printable job
>      Server: no server active
>      Status: accounting at end 'papowell@astart110+094352860' at 09:44:00
>      Status: printing 'papowell@astart110+094352860', closing device at 09:44:00
>      Status: printing 'papowell@astart110+094352860', finished  at 09:44:00
>      Status: subserver status 'JSUCC' for 'papowell@astart110+094352860' \
>                 on attempt 1 at 09:44:00
>      Status: finished operations at 09:44:00
>      Job: papowell@astart110+202228663 status= 1
>      Job: papowell@astart110+202228663 CONTROL=
>      - Hastart110.astart.com
>      - Ppapowell
>      - J/tmp/hi
>      - CA
>      - Lpapowell
>      - Apapowell@astart110+202228663
>      - Qt1
>      - fdfA010663astart110.astart.com
>      - N/tmp/hi
>      - UdfA010663astart110.astart.com
>      Job: papowell@astart110+202228663 HOLDFILE=
>      - active 0
>      - done 0
>      - hold 0
>      - move 0
>     ....

> `

## 17.5 lpc status

The LPC status command is used to show the status of the queues currently being managed by the LPRng server. Note that this form of the command is supported only by LPRng, and is not backwards compatible with BSD LPR implementations.

> `

>     %lpc status all
>      Printer           Printing Spooling Jobs  Server   Slave Redirect Status/Debug
>     lw4@astart4         enabled  enabled    0    none    none
>     lw5@astart4         enabled  enabled    0    none    none

> `

The status display has a heading line and summary of the server status.

## 17.6 Remote Logger Operation

Several sites have wanted a way to provide central logging of job status and/or information. In order to do this, the following functionality is provided with LPRng.

### Logger Network Communication

Options used:

- `logger_destination=`logger information destination
- `logger_pathname=`pathname of temp file for log information
- `logger_max_size=`max size in K of temp file for log information
- `logger_timeout=`time between connection attempts

The printcap/configuration variable `logger_destination` specifies a destination in the standard `host%port` notation used by LPRng. Host is the destination host, and can be a name or IP address. Port is the port on the destination host. A TCP/IP connection is made to the indicated port.

Log information is save in a temporary file specified by `logger_path`, and up to `logger_max_size` K bytes of data will be saved.

If a connection cannot be made to the `logger_destination`, then every `logger_timeout` seconds a new connection attempt will be made. If `logger_timeout` is 0, then a connection attempt will be made every time new data arrives to be logged.

### Logger Messages

Log messages consist of a single line terminated with a newline (`\n`) character.

Each log message reports a system event or status change of the LPD server. When the connection is first established, a complete dump of the status of the LPD server is sent. After this, only status update messages are sent. The remote monitor can force a status dump by simply closing and reopening the connection.

### Message Format

Each message is encoded as a URI escaped string. That is, non-alphanumeric characters are encoded as the 3 character sequence `%xx`, where `xx` is the hexadecimal value of the character. The message has the format `key=value`, where `key` indicates the message type. For example:

> `

>     dump=host=astart4.astart.com%0aprinter=t1%0aprocess=1613%0aupdate_time=1999-03-2
>       3-20:32:17.148%0avalue=queue=holdall 0%25250aprinting_aborted=0x0%25250aprinting
>       _disabled=0x0%25250aspooling_disabled=0x0%25250a%250a%0a

> `

The following keys are used:

1. dump
   A status dump of the current contents of a print queue.

Each message has a set of headers and a value. For example, the decoded dump message from the previous section would be:

> `

>     host=astart4.astart.com
>     printer=t1
>     process=1613
>     update_time=1999-03-23-20:32:17.148
>     value=queue=holdall 0%250aprinting_aborted=0x0%250aprinting_disabled=0x0%250aspo
>       oling_disabled=0x0%250a%0a

> `

Each line consists of a key and a value. The `host` key indicates the host name, `printer` is the print queue, `process` is the process which generated the report or action, `update_time` is the time at which the report was generated, and `value` is the value of the report.

The decoded `value` of the above report is:

> `

>     queue='holdall 0%0aprinting_aborted=0x0%0aprinting_disabled=0x0%0aspooling_dis
>       abled=0x0%0a

> `

The `queue` key provides the current value of the queue control file.

### Dump Messages

Dump messages are generated at the start of operations, and consist of a list of queue status messages.

### LPD Messages

These are used to indicate LPD startup or change in operation.

> `

>     Decode: lpd=host=astart4.astart.com%0aprocess=1672%0aupdate_time=1999-03-23-20:5
>     1:10.507%0avalue=Starting%0a
>     host=astart4.astart.com
>     process=1672
>     update_time=1999-03-23-20:51:10.507
>     value=Starting
>     lpd: 'Starting'

> `

### Job Status Messages - UPDATE

Update messages are used to report changes in the queue contents, such as job arrival.

> `

>     Decode: update=host=astart4.astart.com%0aidentifier=papowell@astart4+676%0anumber=
>      ...
>     host=astart4.astart.com
>     identifier=papowell@astart4+676
>     number=676
>     printer=t1
>     process=1677
>     update_time=1999-03-23-20:51:17.197
>     value=bnrname=papowell%0acf_esc_image=Apapowell@astart4+676%250aCA%250aD1999-03-
>       ...

> `

This update message reports the arrival of a new job at the queue. The `value` field reports the control file contents:

> `

>     cf_esc_image=Apapowell@astart4+676%0aCA%0aD1999-03-23-20:51:17.151%0aHastart4.as
>        tart.com%0aJ/tmp/hi%0aLpapowell%0aPpapowell%0aQt1%0aN/tmp/hi%0afdfA676astart4.as
>        tart.com%0aUdfA676astart4.astart.com%0a
>     class=A
>     date=1999-03-23-20:51:17.151
>     file_hostname=astart4.astart.com
>     fromhost=astart4.astart.com
>     held=0x0
>     hf_name=/var/tmp/LPD/t1/hfA676
>     hold_class=0x0
>     hold_time=0x0
>     identifier=papowell@astart4+676
>     job_time=0x36f86f45
>     jobname=/tmp/hi
>     logname=papowell
>     number=676
>     priority=A
>     queuename=t1
>     size=3
>     transfername=cfA676astart4.astart.com
>     update_time=1999-03-23-20:51:17.187

> `

The `update_time` field in the section above is the time that the job information was last updated. The `cf_esc_image` value is the URL escaped control file information.

### Printer Status Messages - PRSTATUS

These messages report printing or other activity related to a job.

> `

>     Decode: prstatus=host=astart4.astart.com%0aidentifier=papowell@astart4+676%0anumber=
>     676%0aprinter=t1%0aprocess=1692%0aupdate_time=1999-03-23-21:02:04.855%0avalue=
>     finished 'papowell@astart4+676'%252c status 'JSUCC'%0a

>     host=astart4.astart.com
>     identifier=papowell@astart4+676
>     number=676
>     printer=t1
>     process=1692
>     update_time=1999-03-23-21:02:04.855
>     value=finished 'papowell@astart4+676'%2c status 'JSUCC'
>     PRSTATUS: 'finished 'papowell@astart4+676', status 'JSUCC''

> `

## 17.7 LPR -mhost%port and user logging support

The `lpr -m` option is used to request that `lpd` send mail to the user when a job has completed. LPRng extends this to allow mail addresses of the form `host[%port][/(TCP|UPD)]` to request that logging information be sent to the user as well.

The administrator should be aware that this is a possible security loophole, and that the `allow_user_logging` flag must be enabled to allow this operation.

Next Previous Contents