.TH BLD "8" "August 2004"
.SH NAME
bld - A black list daemon
.SH SYNOPSIS
.br
.B bld
-h | [option]
.SH OPTIONS
.TP
\fB\-v\fR
Output version information and exit
.TP
\fB-n\fR
Do not fork to become a daemon
.TP
\fB-a\fR \fIaddress\fR
Address to bind to
.TP
\fB-p\fR \fIport\fR
Port to listen to
.TP
\fB-l\fR \fInumber\fR
Log verbosity (between 0 and 3)
.TP
\fB-t\fR \fInumber\fR
Minimum time interval before blacklisting
.TP
\fB-m\fR \fInumber\fR
Maximum submissions in time interval
.TP
\fB-i\fR \fInumber\fR
IP list size
.TP
\fB-b\fR \fInumber\fR
Blacklist size
.TP
\fB-e\fR \fInumber\fR
Blacklist expiration
.TP
\fB-P\fR \fIfilename\fR
Filename where to save PID
.TP
\fB-T\fR \fInumber\fR
Timeout for client connections
.TP
\fB-u\fR \fIuser\fR
User to run as
.TP
\fB-g\fR \fIgroup\fR
Group to run as
.TP
\fB-f\fR \fIfilename\fR
Use a specific configuration file
.TP
\fB-A\fR \fIfilename\fR
Filename where to find ACLs
.TP
\fB-W\fR \fIfilename\fR
Filename where to find whitelist
.TP
\fB-B\fR \fIfilename\fR
Filename where to store blacklist
.TP
\fB-I\fR \fIfilename\fR
Filename where to store whole IP list
.TP
.SH DESCRIPTION
.PP
By default, the \fBbld\fR daemon listens to requests on port 2905.  Requests
are either IP addresses submissions or checks against the black list.
.PP
\fBbld\fR uses a very simple algorithm to decide whether to add IP
addresses to the blacklist or not. The first time an IP address is
submitted, it is added to an internal list with a timestamp and all
further requests increment a counter for this IP.  As soon as the
minimum time interval is elapsed (default: 30 seconds), and if a maximum
requests ratio is reached (default: 10 submissions in the 30 seconds
interval), the IP is put in the blacklist.  It is then blacklisted for a
configurable time (default: 900 seconds).
.SH PROTOCOL
.PP
Requests sent to \fBbld\fR are rather simple.  Each request or reply is
followed by a linefeed and a carriage return.  A client may only send one
request per TCP session.  As of now, two commands may be used: \fBip\fR
(address submission) and \fBip?\fR (ask if address is blacklisted).
.PP
\fBip=a.b.c.d\fR submits an IP address.  The server acknowledges either
with a \fB200\fR code if the address is not blacklisted or a \fB421\fR
if it is.
.PP
\fBipdecr=a.b.c.d\fR decrements the internal counter for an IP address.
The lowest value for the counter is zero.  The server always acknowledges
with a \fB200\fR code.
.PP
\fBip?=a.b.c.d\fR asks if address is blacklisted.  The server reply may
be \fB421\fR if it is or \fB200\fR if it's not.
.PP
\fBipbl=a.b.c.d\fR forces the insertion in the blacklist.  The server
acknowledges with a \fB200\fR code.
.PP
If using IP based restrictions, the server reply may be \fB600\fR if the
client is not in the correct ACL to perform a request.  Any other error
will generate a reply with a \fB500\fR error code.
.SH NOTES
.PP
\fBbld\fR binds to localhost by default and accepts any local request,
so please make sure that only trusted users can establish a connection
to the daemon.  Please check that all authorized hosts meet the
minimal security requirements before changing this parameter even if
using an access control list (see \fIbld_acl.conf\fR(5)).
.PP
\fBbld\fR will log some statistics if it receives the SIGUSR1 signal.
SIGUSR2 is used to force a dump of both lists in \fBbld\fR working
directory.
.SH FILES
.PP
/etc/bld/bld.conf
/etc/bld/bld_acl.conf
/etc/bld/bld_whitelist.conf
/var/run/bld/bld.pid
/var/run/bld/bld_iplist.dump
/var/run/bld/bld_blacklist.dump
.SH SEE ALSO
.PP
bld.conf(5) bld_acl.conf(5) bld_whitelist.conf(5) bldread(8) bldquery(8)
bldsubmit(8) blddecr(8)
.SH AUTHOR
Olivier Beyssac <obld@r14.freenix.org>