Add man page for black hole sysctl MIBs.

references to follow.

1 files changed, 81 insertions, 0 deletions

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