summaryrefslogtreecommitdiff
path: root/support/dktools/man/man1/pjsnmp.1
diff options
context:
space:
mode:
Diffstat (limited to 'support/dktools/man/man1/pjsnmp.1')
-rw-r--r--support/dktools/man/man1/pjsnmp.11211
1 files changed, 0 insertions, 1211 deletions
diff --git a/support/dktools/man/man1/pjsnmp.1 b/support/dktools/man/man1/pjsnmp.1
deleted file mode 100644
index 92b54ebbfb..0000000000
--- a/support/dktools/man/man1/pjsnmp.1
+++ /dev/null
@@ -1,1211 +0,0 @@
-'\" t
-.\" Title: pjsnmp
-.\" Author: [see the "AUTHOR" section]
-.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
-.\" Date: 11/11/2019
-.\" Manual: \ \&
-.\" Source: \ \&
-.\" Language: English
-.\"
-.TH "PJSNMP" "1" "11/11/2019" "\ \&" "\ \&"
-.\" -----------------------------------------------------------------
-.\" * Define some portability stuff
-.\" -----------------------------------------------------------------
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.\" http://bugs.debian.org/507673
-.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.ie \n(.g .ds Aq \(aq
-.el .ds Aq '
-.\" -----------------------------------------------------------------
-.\" * set default formatting
-.\" -----------------------------------------------------------------
-.\" disable hyphenation
-.nh
-.\" disable justification (adjust text to left margin only)
-.ad l
-.\" -----------------------------------------------------------------
-.\" * MAIN CONTENT STARTS HERE *
-.\" -----------------------------------------------------------------
-.SH "NAME"
-pjsnmp \- Print job transfer over TCP socket with SNMP support
-.SH "SYNOPSIS"
-.sp
-\fBpjsnmp\fR [\fIoption(s)\fR]
-.SH "DESCRIPTION"
-.sp
-Pjsnmp is a filter for the LPRng print system\&. It is used to transfer print job data from the LPRng server to a networked printer\&. This filter does not modify data, it just reads print job data from standard input and transfers that data using a TCP connection\&.
-.sp
-The program uses SNMP to check the printer status before sending the print job, while sending data and after sending the print job\&. Data exchange includes device status (hrDeviceStatus), printer status (hrPrinterStatus), error and warning conditions (hrPrinterDetectedErrorState), page counter value (prtMarkerLifeCount) and the first status text line (prtConsoleDisplayBufferText)\&.
-.sp
-A summary state is derived from the information found:
-.PP
-\fBunreachable\fR
-.RS 4
-SNMP data exchange failed\&.
-
-Probably the printer is turned off or not correctly connected to the network\&.
-.RE
-.PP
-\fBstandby\fR
-.RS 4
-The printer is in power\-save mode as there were no print requests for a longer time\&.
-.RE
-.PP
-\fBidle\fR
-.RS 4
-The printer has nothing to do\&.
-.RE
-.PP
-\fBwarmup\fR
-.RS 4
-The printer is warming up, either after power\-on or when recovering from standby state or errors\&.
-.RE
-.PP
-\fBbusy\fR
-.RS 4
-The printer is printing\&.
-.RE
-.PP
-\fBerror\fR
-.RS 4
-There is any error condition preventing the printer from printing (i\&.e\&. out of paper, out of toner, paper jam\&...)\&. It is not known whether or not the printer has data to print\&.
-.RE
-.PP
-\fBunknown\fR
-.RS 4
-There was an SNMP response but data can not be mapped to one of the states above\&.
-.RE
-.sp
-Before starting print data transfer pjsnmp waits for the printer to reach \fIidle\fR or \fIstandby\fR state so it is secure to use the page counter value\&. After the data transfer pjsnmp waits for the printer to finish the print job until it is in \fIidle\fR or \fIstandby\fR state again\&.
-.sp
-Optionally pjsnmp can be used in conjunction with printqd for print accounting or print quota\&.
-.sp
-The following OIDs are inspected by pjsnmp:
-.PP
-\fBhrDeviceStatus\fR
-.RS 4
-The device status, one from:
-.PP
-\fIunknown\fR
-.RS 4
-The current state of the device is unknown\&.
-.RE
-.PP
-\fIrunning\fR
-.RS 4
-The device is working, no unusual or error condition\&.
-.RE
-.PP
-\fIwarning\fR
-.RS 4
-Unusual or error condition, the device is still operational\&.
-.RE
-.PP
-\fItesting\fR
-.RS 4
-The device is not available (i\&.e\&. in self test)\&.
-.RE
-.PP
-\fIdown\fR
-.RS 4
-Due to errors the device is not available for any use\&.
-.RE
-.RE
-.PP
-\fBhrPrinterStatus\fR
-.RS 4
-The printer status, one from
-.PP
-\fIother\fR
-.RS 4
-States not mentioned below\&.
-.RE
-.PP
-\fIunknown\fR
-.RS 4
-State is unknown, hrDeviceStatus should be
-\fIunknown\fR
-too\&.
-.RE
-.PP
-\fIidle\fR
-.RS 4
-Waiting for a print job (nothing to do)\&.
-.RE
-.PP
-\fIprinting\fR
-.RS 4
-The printer is printing\&.
-.RE
-.PP
-\fIwarmup\fR
-.RS 4
-Warmup after power on or when returning from standby or error\&.
-.RE
-.RE
-.PP
-\fBhrPrinterDetectedErrorState\fR
-.RS 4
-A set of bits indicating error and warning conditions\&. Bit 0 is the MSB in the first response byte, bit 7 is the LSB in the first response byte\&. Bit 8 is the MSB of the second response byte\&...
-.PP
-\fIlow\-paper\fR (bit 0, warning)
-.RS 4
-Paper is low, printer will be out of paper soon\&.
-.RE
-.PP
-\fIno\-paper\fR (bit 1, error)
-.RS 4
-Out of paper\&.
-.RE
-.PP
-\fIlow\-toner\fR (bit 2, warning)
-.RS 4
-Toner is low, printer will be out of toner soon\&.
-.RE
-.PP
-\fIno\-toner\fR (bit 3, error)
-.RS 4
-Out of toner\&.
-.RE
-.PP
-\fIdoor\-open\fR (bit 4, error)
-.RS 4
-Any of the doors (i\&.e\&. to change toner or marker supply) is open\&.
-.RE
-.PP
-\fIpaper\-jam\fR (bit 5, error)
-.RS 4
-Paper jam\&.
-.RE
-.PP
-\fIoffline\fR (bit 6, error)
-.RS 4
-Printer is not working due to error\&.
-.RE
-.PP
-\fIservice\-requested\fR (bit 7, warning)
-.RS 4
-You should either do preventive maintenance (i\&.e\&. cleaning) or press a button on the printer (i\&.e\&. to confirm paper type and size you just inserted)\&.
-.RE
-.PP
-\fIinput\-tray\-missing\fR (bit 8, error)
-.RS 4
-An input tray was removed (i\&.e\&. for filling)\&.
-.RE
-.PP
-\fIoutput\-tray\-missing\fR (bit 9, error)
-.RS 4
-An output tray was removed\&.
-.RE
-.PP
-\fImarker\-supply\-missing\fR (bit 10, error)
-.RS 4
-No marker supply available\&.
-.RE
-.PP
-\fIoutput\-near\-full\fR (bit 11, warning)
-.RS 4
-Output tray is nearly full, will become full soon\&.
-.RE
-.PP
-\fIoutput\-full\fR (bit 12, error)
-.RS 4
-Output tray is full\&.
-.RE
-.PP
-\fIinput\-tray\-empty\fR (bit 13, warning)
-.RS 4
-At least one input tray is empty\&.
-.RE
-.PP
-\fIoverdue\-preventive\-maintenance\fR (bit 14, warning)
-.RS 4
-Some preventive maintenance is necessary\&.
-.RE
-.RE
-.PP
-\fBprtMarkerLifeCount\fR
-.RS 4
-The number of print impressions, typically the number of printed pages (either in printers life time or since power\-on)\&. For duplex printing front and back page are counted as 2\&.
-.RE
-.PP
-\fBprtConsoleDisplayBufferText\fR
-.RS 4
-The status text shown in the first line of the printers console\&.
-.RE
-.SH "GETTING THE SUMMARY STATE FROM SNMP INFORMATION"
-.sp
-\fBStage 1: Device and printer status\fR
-.sp
-In the first processing stage a summary state is chosen for the combination of device status and printer status\&.
-.TS
-allbox tab(:);
-ltB ltB ltB.
-T{
-Device status
-T}:T{
-Printer status
-T}:T{
-Summary state
-T}
-.T&
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt.
-T{
-.sp
-unknown
-T}:T{
-.sp
-other
-T}:T{
-.sp
-unknown
-T}
-T{
-.sp
-unknown
-T}:T{
-.sp
-unknown
-T}:T{
-.sp
-unknown
-T}
-T{
-.sp
-unknown
-T}:T{
-.sp
-idle
-T}:T{
-.sp
-unknown
-T}
-T{
-.sp
-unknown
-T}:T{
-.sp
-printing
-T}:T{
-.sp
-unknown
-T}
-T{
-.sp
-unknown
-T}:T{
-.sp
-warmup
-T}:T{
-.sp
-warmup
-T}
-T{
-.sp
-running
-T}:T{
-.sp
-other
-T}:T{
-.sp
-standby
-T}
-T{
-.sp
-running
-T}:T{
-.sp
-unknown
-T}:T{
-.sp
-unknown
-T}
-T{
-.sp
-running
-T}:T{
-.sp
-idle
-T}:T{
-.sp
-idle
-T}
-T{
-.sp
-running
-T}:T{
-.sp
-printing
-T}:T{
-.sp
-busy
-T}
-T{
-.sp
-running
-T}:T{
-.sp
-warmup
-T}:T{
-.sp
-warmup
-T}
-T{
-.sp
-warning
-T}:T{
-.sp
-other
-T}:T{
-.sp
-standby
-T}
-T{
-.sp
-warning
-T}:T{
-.sp
-unknown
-T}:T{
-.sp
-unknown
-T}
-T{
-.sp
-warning
-T}:T{
-.sp
-idle
-T}:T{
-.sp
-idle
-T}
-T{
-.sp
-warning
-T}:T{
-.sp
-printing
-T}:T{
-.sp
-busy
-T}
-T{
-.sp
-warning
-T}:T{
-.sp
-warmup
-T}:T{
-.sp
-warmup
-T}
-T{
-.sp
-testing
-T}:T{
-.sp
-other
-T}:T{
-.sp
-unknown
-T}
-T{
-.sp
-testing
-T}:T{
-.sp
-unknown
-T}:T{
-.sp
-unknown
-T}
-T{
-.sp
-testing
-T}:T{
-.sp
-idle
-T}:T{
-.sp
-unknown
-T}
-T{
-.sp
-testing
-T}:T{
-.sp
-printing
-T}:T{
-.sp
-unknown
-T}
-T{
-.sp
-testing
-T}:T{
-.sp
-warmup
-T}:T{
-.sp
-warmup
-T}
-T{
-.sp
-down
-T}:T{
-.sp
-other
-T}:T{
-.sp
-error
-T}
-T{
-.sp
-down
-T}:T{
-.sp
-unknown
-T}:T{
-.sp
-error
-T}
-T{
-.sp
-down
-T}:T{
-.sp
-idle
-T}:T{
-.sp
-error
-T}
-T{
-.sp
-down
-T}:T{
-.sp
-printing
-T}:T{
-.sp
-error
-T}
-T{
-.sp
-down
-T}:T{
-.sp
-warmup
-T}:T{
-.sp
-warmup
-T}
-.TE
-.sp 1
-.sp
-An SNMP model can be used to change the mapping from device/printer status to summary states\&.
-.sp
-\fBStage 2: Checking printer detected error state\fR
-.sp
-If the printer detected error state contains any condition marked with \(lqError\(rq in the hrPrinterDetectedErrorState table, the summary state is changed to \fIerror\fR\&.
-.sp
-If the :pjsnmp\-pdes\-always flag is disabled in the printcap entry, this check is only applied if stage 1 resulted in \fIunknown\fR\&.
-.sp
-An SNMP model can be used to change the conditions interpreted as errors\&.
-.sp
-\fBStage 3: Status text from the display\fR
-.sp
-An SNMP model can be used to map status texts from the printers first display line to summary states \fIbusy\fR, \fIidle\fR and \fIstandby\fR\&.
-.sp
-In the model you can configure to inspect the display line text always or for summary state \fIunknown\fR only\&.
-.sp
-\fBStage 4: Mapping unknown to busy\fR
-.sp
-If the summary state is \fIunknown\fR and :pjsnmp\-unknown\-busy is set in the printcap entry, the state is shown as \fIbusy\fR\&.
-.SH "OPTIONS"
-.sp
-All options for pjsnmp are set by the LPRng print system\&.
-.SH "EXIT STATUS"
-.sp
-0 on success, 3 to remove the print job due to errors or 6 to hold the print job\&.
-.SH "ENVIRONMENT"
-.sp
-LPRng places a copy of the printcap entry for the printer in the PRINTCAP_ENTRY environment variable\&.
-.SH "FILES \- THE PRINTCAP FILE"
-.sp
-The ${sysconfdir}/lpd/printcap file configures the LPRng print queues\&.
-.sp
-Each queue description is started by the queue name without a leading colon\&. A list of configuration entries follows, each one is separated from previous contents by a colon\&. This list of configuration entries can span multiple lines, if the first non\-whitespace character on a line is a colon the line is the continuation line\&.
-.sp
-Each entry can be either a boolean value or a \fIkey\fR=\fIvalue\fR pair\&.
-.sp
-A boolean value does not contain an equal sign \(lq=\(rq\&. A boolean entry without \(lq@\(rq is turned on (true), a name followed by \(lq@\(rq turns a setting off (false)\&.
-.sp
-The following entries are relevant for pjsnmp:
-.PP
-\fB:server\fR
-.RS 4
-Pjsnmp is used in the configuration on the server only, not by the client programs\&.
-.RE
-.PP
-\fB:lp=|\fR\fI/path\&.../pjsnmp\fR
-.RS 4
-IO device names started by \(lq|\(rq indicate a program to run as a filter\&. The program obtains the print data to transmit from it\*(Aqs standard input\&. We use the pjsnmp program here, the entries below are used to configure it\&.
-.RE
-.PP
-\fB:pjsnmp\-host=\fR\fIhost\fR
-.RS 4
-The host name or IPv4 address of the printer\&. Default: none\&. LPRng uses the colon as separator between configuration entries, IPv6 uses colons to separate words\&. So we can not specify IPv6 addresses here\&.
-.RE
-.PP
-\fB:pjsnmp\-port=\fR\fInumber\fR
-.RS 4
-The port number of the printer (default: 9100)\&.
-.RE
-.PP
-\fB:pjsnmp\-local\-port=\fR\fInumber\fR
-.RS 4
-Local port number to use\&. Default: 0 (use arbitrary port)\&.
-\fINote:\fR
-When running multiple print queues on a server you should use different local port numbers for each queue\&. I recommend to leave this setting at the default and let the system choose an arbitrary local port\&.
-.RE
-.PP
-\fB:pjsnmp\-read\-response\fR
-.RS 4
-Flag: Do receive operations on network socket\&. Default: off\&.
-.RE
-.PP
-\fB:pjsnmp\-ordrel\fR
-.RS 4
-Flag: Do an orderly release of the TCP connection after transferring the print data\&. Default: off\&.
-.RE
-.PP
-\fB:pjsnmp\-version=\fR\fIstring\fR
-.RS 4
-The SNMP version to use, \(lq1\(rq, \(lq2c\(rq, or \(lq3\(rq\&. Default: 1\&.
-.RE
-.PP
-\fB:pjsnmp\-community=\fR\fIname\fR
-.RS 4
-The SNMP community name\&. Default: \(lqpublic\(rq\&.
-.RE
-.PP
-\fB:pjsnmp\-during\-transfer\fR
-.RS 4
-Flag: Do SNMP data transfer before each attempt to send data\&. Default: on\&. If the option is disabled, pjsnmp does SNMP queries only on failed attempts to send data\&.
-.RE
-.PP
-\fB:pjsnmp\-pdes\-always\fR
-.RS 4
-Flag: Use printer detected error state conditions for all device/printer status combinations\&. Default: on\&. If the flag is disabled, these conditions are used only if the summary state is
-\fIunknown\fR\&.
-.RE
-.PP
-\fB:pjsnmp\-model\-name=\fR\fIname\fR
-.RS 4
-SNMP model to use for printer\&. Use of SNMP models is optional, only necessary for printers not using the reasonable SNMP implementation below\&. Default: none\&.
-.RE
-.PP
-\fB:pjsnmp\-model\-file=\fR\fIpath\fR
-.RS 4
-File name containing the SNMP model descriptions\&. Default ${datarootdir}/dktools/pjsnmp\&.conf \&.
-.RE
-.PP
-\fB:pjsnmp\-unknown\-busy\fR
-.RS 4
-Flag: Indicate summary state
-\fIunknown\fR
-as
-\fIbusy\fR\&. Default: off\&.
-.RE
-.PP
-\fB:pjsnmp\-force\-printable\-status\-text\fR
-.RS 4
-Flag: Show status text from printer in status file even if it contains non\-ASCII characters (these characters are replaced by a question mark in output)\&. Default: on\&.
-.RE
-.PP
-\fB:pjsnmp\-ignore\-failed\-session\fR
-.RS 4
-Flag: Ignore failure to establish SNMP session\&. Default: off\&. If this flag is turned on pjsnmp attempts to transfer print data even if the program failed to establish an SNMP session and thus can not do state monitoring or accounting\&.
-.RE
-.PP
-\fB:pjsnmp\-require\-printing=\fR\fInumber\fR
-.RS 4
-Timeout at job end for suspicious transitions to summary state
-\fIidle\fR
-or
-\fIstandby\fR\&. Default: 600\&.
-.sp
-On suspicious transitions we give the printer some time to start or resume printing\&. Suspicious transitions include:
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-Transition from
-\fIerror\fR
-to
-\fIidle\fR
-or
-\fIstandby\fR\&. After recovering from an error condition some printers go from
-\fIerror\fR
-to
-\fIbusy\fR
-via
-\fIidle\fR
-or
-\fIstandby\fR\&. Such intermediate
-\fIidle\fR
-or
-\fIstandby\fR
-states do not indicate the end of a print job\&.
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-Transitions to
-\fIidle\fR
-or
-\fIstandby\fR
-if the page counter value did not change since start of job or last time seeing
-\fIerror\fR\&. For very short print jobs the printer starts printing some seconds after the data transfer was finished\&.
-.RE
-.RE
-.PP
-\fB:pjsnmp\-accounting\-enable\fR
-.RS 4
-Flag: Pass pagecounters to an accounting/quota system\&. Default: off\&.
-.RE
-.PP
-\fB:pjsnmp\-accounting\-check\fR
-.RS 4
-Flag: Check a users permission to print to a queue before transferring data\&. Default: off\&. Requires :accounting_enable\&. To receive responses from the quota/accounting system we must use one of three methods to connect to the accounting system:
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-Local UNIX domain socket (recommended method)\&. Specify the path name of the accounting systems local UNIX domain socket in :pjsnmp\-accounting\-file\&.
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-Network connection\&. Specify host name and port number in :pjsnmp\-accounting\-host and :pjsnmp\-accounting\-port\&.
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-Pipe program\&. A program to handle accounting data is specified in :pjsnmp\-accounting\-file using \(lq|\(rq\&. The programs exit status indicates how to handle the print job: 0 to transfer data to the printer, 3 to remove the job (printing is denied), 6 to hold the job in the queue (printing is denied)\&.
-.RE
-.RE
-.PP
-\fB:pjsnmp\-accounting\-file=\fR\fIpath\fR
-.RS 4
-Path name for socket or accounting file\&. Default: none\&. A path started by \(lq|\(rq indicates a program to use in a pipe\&. The pipe is uni\-directional by definition\&. Pjsnmp writes accounting data into the pipe, the specified program reads this data from it\*(Aqs standard input\&.
-.sp
-For permission checks the programs exit status code indicates how to handle the print job (0=print, 3=remove job when printing is denied, 6=hold job when printing is denied)\&.
-.RE
-.PP
-\fB:pjsnmp\-accounting\-host=\fR\fIhost\fR
-.RS 4
-Host name for network connection\&. Note: Neither encryption nor authentication is used when transferring accounting data over network\&. The recommended method is to run the accounting software on the print server and use a local UNIX domain socket for communication\&.
-.RE
-.PP
-\fB:pjsnmp\-accounting\-port=\fR\fInumber\fR
-.RS 4
-Port number for network connection\&.
-.RE
-.PP
-\fB:pjsnmp\-non\-ascii\-job\-title\fR
-.RS 4
-Flag: Allow non\-ASCII characters in job title for accounting\&. Default: Off\&.
-.RE
-.PP
-\fB:pjsnmp\-allow\-printing\-if\-accounting\-connection\-failed\fR
-.RS 4
-Flag: Allow printing if no connection to accounting system is possible\&. Default: off\&.
-.RE
-.PP
-\fB:pjsnmp\-unreachable\-timeout\-start=\fR\fInumber\fR
-.RS 4
-Timeout (number of seconds) to abort the print job if the printer is unreachable at start of job\&. Default: 3600\&.
-.RE
-.PP
-\fB:pjsnmp\-unreachable\-timeout\-end=\fR\fInumber\fR
-.RS 4
-Timeout (number of seconds) to abort processing if the printer is unreachable after transferring print job data\&. Default: 120\&.
-.RE
-.PP
-\fB:pjsnmp\-unreachable\-timeout\-printing=\fR\fInumber\fR
-.RS 4
-Timeout (number of seconds) to abort data transfer if the printer is unreachable during data transfer\&. Default: 120\&.
-.RE
-.PP
-\fB:pjsnmp\-unwriteable\-timeout\-printing=\fR\fInumber\fR
-.RS 4
-Timeout (number of seconds) to abort data transfer if the network socket is not writeable during data transfer\&. Default: 900\&.
-.RE
-.PP
-\fB:pjsnmp\-verbose\fR
-.RS 4
-Flag: Verbose output (show command line arguments)\&.
-.RE
-.SH "FILES \- SNMP MODEL FILE"
-.sp
-The ${datarootdir}/dktools/print\-snmp\&.conf file (or any other file you specify in the :pjsnmp\-model\-file entry in the printcap file) configures SNMP models\&.
-.sp
-Lines started by a raute character \(lq#\(rq are comments\&.
-.sp
-The file contains a list of SNMP models\&.
-.sp
-Each model description consists of a name line and a list of data lines\&.
-.sp
-The name line contains the model name in square brackets\&.
-.sp
-Data lines consist of key and value, separated by equal sign \(lq=\(rq\&. Both key and value can consist of multiple text words\&.
-.sp
-The following data lines are allowed:
-.PP
-\fBmap =\fR \fIdevice\fR\fB/\fR\fIprinter\fR \fIsummary\fR
-.RS 4
-Set mapping from a device status / printer status combination to a summary state\&.
-.RE
-.PP
-\fBerror condition =\fR \fIcondition\fR
-.RS 4
-Change the condition set from hrPrinterDetectedErrorState treated as errors\&. The first \(lqerror condition =\(rq line resets the condition set, so you can build a new one from scratch\&.
-.sp
-See the description of hrPrinterDetectedErrorState above for condition names\&. The default set contains the conditions marked as error in the description\&.
-.RE
-.PP
-\fBadd error condition =\fR \fIcondition\fR
-.RS 4
-Modify the condition set from hrPrinterDetectedErrorState treated as errors starting with the default set\&.
-.RE
-.PP
-\fBstatus text oid =\fR \fIoid\fR
-.RS 4
-OID delivering the status text shown in the printers first display line\&. The OID must be specified in
-\fInumeric\fR
-notation, 1\&.3\&.6\&.1\&.2\&.1\&.43\&.16\&.5\&.1\&.2\&.1\&.1 is the default\&.
-.RE
-.PP
-\fBtext standby =\fR \fItext\fR
-.RS 4
-Specifies a text signaling standby state\&.
-.sp
-Texts can be specified in double quotes or as hexadecimal byte sequence, i\&.e\&.:
-.sp
-.if n \{\
-.RS 4
-.\}
-.nf
-text standby = "Power Save"
-.fi
-.if n \{\
-.RE
-.\}
-.sp
-is equivalent to
-.sp
-.if n \{\
-.RS 4
-.\}
-.nf
-text standby = 50 6F 77 65 72 20 53 61 76 65
-.fi
-.if n \{\
-.RE
-.\}
-.sp
-The status text retrieved from the printer must match the specified text exactly\&.
-.RE
-.PP
-\fBstart standby =\fR \fItext\fR
-.RS 4
-Specifies a start of texts indicating summary state
-\fIstandby\fR\&.
-.sp
-Example
-.sp
-.if n \{\
-.RS 4
-.\}
-.nf
-start standby = "Power Save"
-.fi
-.if n \{\
-.RE
-.\}
-.sp
-detects
-\fIstandby\fR
-state if the printer returns status text \(lqPower Save Mode On\(rq\&.
-.RE
-.PP
-\fBtext idle =\fR \fItext\fR
-.RS 4
-Specifies texts indicating summary state
-\fIidle\fR\&.
-.RE
-.PP
-\fBstart idle =\fR \fItext\fR
-.RS 4
-Specifies a start of texts indicating summary state
-\fIidle\fR\&.
-.RE
-.PP
-\fBtext busy =\fR \fItext\fR
-.RS 4
-Specifies texts indicating summary state
-\fIbusy\fR\&.
-.RE
-.PP
-\fBstart busy =\fR \fItext\fR
-.RS 4
-Specifies a start of texts indicating summary state
-\fIbusy\fR\&.
-.RE
-.PP
-\fBtext unknown =\fR \fItext\fR
-.RS 4
-Specifies texts indicating summary state
-\fIunknown\fR\&.
-.RE
-.PP
-\fBstart unknown =\fR \fItext\fR
-.RS 4
-Specifies a start of texts indicating summary state
-\fIunknown\fR\&.
-.RE
-.PP
-\fBtext error =\fR \fItext\fR
-.RS 4
-Specifies texts indicating summary state
-\fIerror\fR\&.
-.RE
-.PP
-\fBstart error =\fR \fItext\fR
-.RS 4
-Specifies a start of texts indicating summary state
-\fIerror\fR\&.
-.RE
-.PP
-\fBtext warmup =\fR \fItext\fR
-.RS 4
-Specifies texts indicating summary state
-\fIwarmup\fR\&.
-.RE
-.PP
-\fBstart warmup =\fR \fItext\fR
-.RS 4
-Specifies a start of texts indicating summary state
-\fIwarmup\fR\&.
-.RE
-.PP
-\fBalways use status text =\fR \fIboolean\fR
-.RS 4
-Flag: Use status text for all summary states, default: off\&. If the flag is disabled, status texts are used only if the summary state found so far is
-\fIunknown\fR\&.
-.RE
-.SH "NOTES"
-.sp
-Different printer manufacturers use different interpretations of hrDeviceStatus, hrPrinterStatus and hrPrinterDetectedErrorState\&.
-.sp
-This program uses DK libraries version 4\&.
-.sp
-It is not available on the Windows platform\&.
-.sp
-Written as a simple program (not an application) it is not relocatable, all diagnostic messages and output texts are in English\&.
-.SH "NOTES \- REASONABLE SNMP IMPLEMENTATION"
-.sp
-The first printers I used with pjsnmp followed the table found in [Edl2003] and a similar table found in RFC 3805\&.
-.TS
-allbox tab(:);
-ltB ltB ltB.
-T{
-Printer status
-T}:T{
-hrDeviceStatus
-T}:T{
-hrPrinterStatus
-T}
-.T&
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt
-lt lt lt.
-T{
-.sp
-Normal, waiting for job
-T}:T{
-.sp
-running
-T}:T{
-.sp
-idle
-T}
-T{
-.sp
-Busy (printing)
-T}:T{
-.sp
-running
-T}:T{
-.sp
-printing
-T}
-T{
-.sp
-Non\-critical alert
-T}:T{
-.sp
-warning
-T}:T{
-.sp
-idle or printing
-T}
-T{
-.sp
-Unavailable (can\(cqt print)
-T}:T{
-.sp
-down
-T}:T{
-.sp
-other
-T}
-T{
-.sp
-Moving offline
-T}:T{
-.sp
-warning
-T}:T{
-.sp
-idle or printing
-T}
-T{
-.sp
-Offline (no printing possible)
-T}:T{
-.sp
-down
-T}:T{
-.sp
-other
-T}
-T{
-.sp
-Moving online (recovering from error or standby)
-T}:T{
-.sp
-down
-T}:T{
-.sp
-warmup
-T}
-T{
-.sp
-Standby
-T}:T{
-.sp
-running
-T}:T{
-.sp
-other
-T}
-.TE
-.sp 1
-.sp
-Some important points from the table:
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-The printer is either waiting for the next job or in standby if the device status is
-\fIrunning\fR
-or
-\fIwarning\fR
-and the printer status is
-\fIidle\fR
-or
-\fIother\fR\&.
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-The device status is
-\fIdown\fR
-for serious errors preventing the printer from printing\&.
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-The device status
-\fIwarning\fR
-indicates only conditions not preventing the printer from printing\&.
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-If the printer has print data but any conditions prevents printing, one of the \(lqError\(rq condition bits in hrPrinterDetectedErrorState is set\&.
-.RE
-.SH "NOTES \- THE SPECIAL SNMP IMPLEMENTATION"
-.sp
-Unfortunately some printer manufacturers use the \fIwarning\fR/\fIother\fR combination both for \(lqprinter is idle but there is a warning condition\(rq and for \(lqprinting interrupted due to error like out of paper, out of toner\&...\(rq\&.
-.sp
-Very special implementations show only warning conditions in hrPrinterDetectedErrorState in these situations\&.
-.SH "NOTES \- CONCLUSION"
-.sp
-In the default configuration pjsnmp handles printers with a reasonable SNMP implementation\&. SNMP models are required to handle the special SNMP implementations\&.
-.SH "AUTHOR"
-.sp
-Dirk Krause
-.SH "COPYRIGHT AND LICENSE"
-.sp
-Copyright (c) 2016, Dirk Krause
-.sp
-All rights reserved\&.
-.sp
-Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer\&.
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution\&.
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-Neither the name of the copyright holder(s) nor the names of contributors may be used to endorse or promote products derived from this software without specific prior written permission\&.
-.RE
-.sp
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \(lqAS IS\(rq AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED\&. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE\&.
-.SH "SEE ALSO"
-.TS
-tab(:);
-lt lt
-lt lt.
-T{
-.sp
-SF project page
-T}:T{
-.sp
-http://sourceforge\&.net/projects/dktools
-T}
-T{
-.sp
-DK tools home page
-T}:T{
-.sp
-http://sourceforge\&.net/p/dktools/wiki/dk\-ls/
-T}
-.TE
-.sp 1
-.SH "LITERATURE"
-.PP
-Edl2003
-.RS 4
-H\&. Edlund: Design and Implementation of Accounting and Status Notification for the LPRng Print Spooler\&. Bachelor\(cqs Thesis, Linköping University, LITH\-IDA\-EX\-ING\(em03/019\(emSE
-.RE