=head1	NAME

fsnmp - Print filter using SNMP for print accounting.

=head1	SYNOPSIS

  fsnmp [<options>]

=head1	DESCRIPTION

Fsnmp is a filter to be used by the LPRng print system to transfer
print data from the print server to the printer using a TCP connection.
Before the data transfer is started the filter uses SNMP to check whether
the printer is ready and to retrieve the page count. After sending data
the filter waits again until the printer is ready and retrieves the page count.

=head1	OPTIONS

The program implements options as required by the LPRng print system.

=head1	RETURN VALUE

The program returns an exit status code as required by the LPRng print
system.

=head1	EXAMPLE

Let's assume your printer has an IP address 192.168.1.99.

In the /etc/lprng/printcap file create an entry

  lp
  	:lp=/dev/null
	:filter=/usr/local/bin/fsnmp

The filter processes the input, standard output from the fsnmp filter is
thrown away.

Create /etc/fsnmp.conf

  [lp]
  lp                         = 192.168.1.99%9100
  snmp version               = 1
  snmp community             = public
  ctrl-d at end              = yes
  shutdown data socket       = no
  minimum pagecount time     = 30
  shutdown accounting socket = yes

so fsnmp knows how to handle the printer.

Restart LPRng.

=head1	FILES

The /etc/fsnmp.conf file (probably /usr/local/etc/fsnmp.conf) contains a list
of printer definitions for fsnmp.
Each definition is consists the printer name in square brackets, followed
by key/value pairs (one per line). Key and value are separated by ``=''.

The following keys can occur:

=over	6

=item	B<lp>

Host and port separated by ``%''. The host can be specified by name
or IP address.

=item	B<snmp version>

The SNMP protocol version (1, 2c, 2p or 3).

=item	B<snmp community>

The SNMP community name.

=item	B<ctrl-d at end>

Boolean, if this option is set fsnmp ensured that the last byte sent to the
printer is a CTRL-D (end of file marker).

=item	B<ctrl-d at start>

Boolean, if this option is set fsnmp ensures that the first bytesent to
the printer is CTRL-D.

=item	B<data transfer port range>

Two numeric values (separated by spaces) to choose a range of local
port numbers.

=item	B<shutdown data socket>

Boolean, may be ``yes'' or ``no''. If this option is turned on fsnmp
attempts a clean TCP/IP shutdown on the data socket (fsnmp shuts down
the socket for writing and attempts to read from the socket until a
``no more data available'' condition occurs.

Most printers do not handle socket shutdown properly, so this option
should be turned off. This allows fsnmp to simply close the socket
after transferring data.

=item	B<minimum pagecount time>

When retrieving the pagecount after job transfer fsnmp waits for the
printer to indicate ``ready'' and to have a pagecount larger than
the pagecount before the job. In rare cases sending a PS job does
not result in a printed page, so the pagecount does not increase.
This option sets a timeout for the wait operation.

=item	B<accounting destination>

String where to send accounting data. Must be one of the following:

=over	12

=item	I<filename>

Name of the accounting file to write.

=item	B<|>I<command>

The specified command is opened as a pipe, accounting data is fed into
the commands standard input.

=item	I<host>B<%>I<port>

Send accounting data overnetwork to the specified host and port.

=back

=item	B<accounting port range>

Two numbers separated by spaces, local port numbers to use when connecting
to a remote accounting process.

=item	B<shutdown accounting socket>

Boolean, configures a clean shutdown of the accounting network socket.

=back

=head1	AUTHOR

Dirk Krause

=head1	COPYRIGHT AND LICENSE

Copyright (c) 2010, Dirk Krause
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

 * Redistributions of source code must retain the above
   copyright notice, this list of conditions and the
   following disclaimer.

 * 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.

 * Neither the name of the Dirk Krause nor the names of
   contributors may be used to endorse or promote products
   derived from this software without specific prior written
   permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 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.

=head1	SEE ALSO

prqd(1), http://dktools.sourceforge.net/fsnmp.html

