Add man page for black hole sysctl MIBs.

references to follow.

2 files changed, 83 insertions, 2 deletions

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 30ec90f..4f328aa 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -1,7 +1,7 @@
 #	@(#)Makefile	8.1 (Berkeley) 6/18/93
 
-MAN4=	bpf.4 bridge.4 ccd.4 cd.4 ch.4 da.4 ddb.4 divert.4 drum.4 \
-	dummynet.4 fd.4 fpa.4 \
+MAN4=	blackhole.4 bpf.4 bridge.4 ccd.4 cd.4 ch.4 da.4 ddb.4 \
+	divert.4 drum.4 dummynet.4 fd.4 fpa.4 \
 	icmp.4 ifmib.4 iic.4 iicbb.4 iicbus.4 iicsmb.4 \
 	inet.4 intpm.4 intro.4 ip.4 ipfirewall.4 kld.4 \
 	lo.4 lp.4 lpbb.4 lpt.4 natm.4 netintro.4 \
diff --git a/share/man/man4/blackhole.4 b/share/man/man4/blackhole.4
new file mode 100644
index 0000000..91e2224
--- /dev/null
+++ b/share/man/man4/blackhole.4
@@ -0,0 +1,81 @@
+.\"
+.\" blackhole - drop refused TCP or UDP connects
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. 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.
+.\"
+.\"
+.\" $Id: lptcontrol.8,v 1.9 1999/05/28 02:09:46 ghelmer Exp $
+.Dd August 17, 1999
+.Dt BLACKHOLE 4
+.Os FreeBSD 
+.Sh NAME
+.Nm \&blackhole 
+.Nd a
+.Xr sysctl 8
+MIB for manipulating behaviour in respect of refused TCP or UDP connection
+attempts.
+.Sh SYNOPSIS
+.Nm \&sysctl net.inet.tcp.blackhole
+.Nm \&sysctl net.inet.udp.blackhole
+.Pp
+.Nm \&sysctl -w net.inet.tcp.blackhole=[1 | 0]
+.Nm \&sysctl -w net.inet.udp.blackhole=[1 | 0]
+.Sh DESCRIPTION
+The
+.Nm
+.Xr sysctl 8
+MIB is used to control system behaviour when connection requests
+are received on TCP or UDP ports where there is no socket listening.
+.Pp
+Normal behaviour, when a TCP SYN segment is received on a port where
+there is no socket accepting connections, is for the system to return
+a RST segment, and drop the connection.  The connecting system will
+see this as a "Connection reset by peer".  By turning the TCP black
+hole MIB on, the incoming SYN segment is merely dropped, and no
+RST is sent, making the system appear as a blackhole.
+.Pp
+In the UDP instance, enabling blackhole behaviour turns off the sending
+of an ICMP port unreachable message in response to a UDP datagram which
+arrives on a port where there is no socket listening.  It must be noted
+that this behaviour will prevent remote systems from running
+.Xr traceroute 8
+to your system.
+.Pp
+The blackhole behaviour is useful to slow down anyone who is port scanning
+your system, in order to try and detect vulnerable services on your system.
+It could potentially also slow down someone who is attempting a denial
+of service against your system.
+.Pp
+.Sh WARNING
+The TCP and UDP blackhole features should not be regarded as a replacement
+for
+.Xr ipfw 8
+as a tool for firewalling your system.  In order to create a highly
+secure system, you should use
+.Xr ipfw 8
+to protect your system, and not the blackhole feature.
+.Pp
+This mechanism is not a substitute for securing your system,
+but should be used together with other security mechanisms.
+.Pp
+.Sh "SEE ALSO"
+.Xr ipfw 8
+.Xr sysctl 8
+.Xr ip 4
+.Xr tcp 4
+.Xr udp 4
+.Sh AUTHORS
+.An Geoffrey M. Rehmet
+.Sh HISTORY
+The TCP and UDP
+.Nm 
+MIBs
+first appeared in
+.Fx 4.0