Differential D10604 Diff 28074 contrib/blacklist/lib/libblacklist.3

Changeset View

Standalone View

contrib/blacklist/lib/libblacklist.3

	Show All 21 Lines
	.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR			.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
	.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF			.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
	.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS			.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
	.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN			.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
	.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)			.\" 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			.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
	.\" POSSIBILITY OF SUCH DAMAGE.			.\" POSSIBILITY OF SUCH DAMAGE.
	.\"			.\"
	.Dd January 22, 2015			.Dd May 5, 2017
				wblockUnsubmitted Done Inline Actions Bump .Dd for this update. wblock: Bump .Dd for this update.
	.Dt LIBBLACKLIST 3			.Dt LIBBLACKLIST 3
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm blacklist_open ,			.Nm blacklist_open ,
	.Nm blacklist_close ,			.Nm blacklist_close ,
	.Nm blacklist_r ,			.Nm blacklist_r ,
	.Nm blacklist ,			.Nm blacklist ,
	.Nm blacklist_sa			.Nm blacklist_sa
	Show All 32 Lines
	The			The
	.Fn blacklist_close			.Fn blacklist_close
	function frees all memory and resources used.			function frees all memory and resources used.
	.Pp			.Pp
	The			The
	.Fn blacklist			.Fn blacklist
	function sends a message to			function sends a message to
	.Xr blacklistd 8 ,			.Xr blacklistd 8 ,
	with an			with an integer
	.Ar action			.Ar action
	argument specifying			argument specifying the type of notification,
	.Dv 1
	for a failed connection or
	.Dv 0
	for a successful connection,
	a file descriptor			a file descriptor
	.Ar fd			.Ar fd
	specifying the accepted file descriptor connected to the client,			specifying the accepted file descriptor connected to the client,
	and an optional message in the			and an optional message in the
	.Ar msg			.Ar msg
	argument.			argument.
	.Pp			.Pp
	The			The
				.Ar action
				parameter can take these values:
				wblockUnsubmitted Done Inline Actions parameter can take these values: wblock: ```parameter can take these values:```
				.Bl -tag -width ".Va BLACKLIST_ABUSIVE_BEHAVIOR"
				.It Va BLACKLIST_AUTH_FAIL
				There was an unsuccessful authentication attempt.
				wblockUnsubmitted Done Inline Actions s/successful/unsuccessful/ s/authenticatation/authentication/ wblock: s/successful/unsuccessful/ s/authenticatation/authentication/
				wblockUnsubmitted Done Inline Actions These sentences all start with "Signal", but that is implied from the context. Might make sense to leave out the "Signal that" and just define the values. For example: There was an unsuccessful authentication attempt. A user has successfully authenticated. wblock: These sentences all start with "Signal", but that is implied from the context. Might make…
				.It Va BLACKLIST_AUTH_OK
				A user successfully authenticated.
				.It Va BLACKLIST_ABUSIVE_BEHAVIOR
				The sending daemon has detected abusive behavior
				from the remote system. The remote address should
				be blocked as soon as possible.
				.It Va BLACKLIST_BAD_USER
				The sending daemon has determined the username
				presented for authentication is invalid. The
				.Xr blacklistd 8
				daemon compares the username to a configured list of forbidden
				usernames and
				wblockUnsubmitted Done Inline Actions s/is matched/matches/ Or maybe "is detected". Just not sure about "is matched". wblock: s/is matched/matches/ Or maybe "is detected". Just not sure about "is matched".
				blocks the address immediately if a forbidden username matches.
				(The
				.Ar BLACKLIST_BAD_USER
				support is not currently available.)
				.El
				.Pp
				The
	.Fn blacklist_r			.Fn blacklist_r
	function is more efficient because it keeps the blacklist state around.			function is more efficient because it keeps the blacklist state around.
	.Pp			.Pp
	The			The
	.Fn blacklist_sa			.Fn blacklist_sa
	and			and
	.Fn blacklist_sa_r			.Fn blacklist_sa_r
	functions can be used with unconnected sockets, where			functions can be used with unconnected sockets, where
	.Xr getpeername 2			.Xr getpeername 2
	will not work, the server will pass the peer name in the message.			will not work, the server will pass the peer name in the message.
	.Pp			.Pp
	All functions log errors to			By default,
	.Xr syslogd 8 .			.Xr syslogd 8
				is used for message logging.
				wblockUnsubmitted Done Inline Actions Rearranging this makes it a bit more solid: By default, .Fn syslog is used for message logging. The internal .Fn bl_create can be used to create the internal state and specify a custom logging function. wblock: Rearranging this makes it a bit more solid: ```By default, .Fn syslog is used for message…
				The internal
				.Fn bl_create
				function can be used to create the required internal
				state and specify a custom logging function.
	.Sh RETURN VALUES			.Sh RETURN VALUES
	The function			The function
	.Fn bl_open			.Fn bl_open
	returns a cookie on success and			returns a cookie on success and
	.Dv NULL			.Dv NULL
	on failure setting errno to an appropriate value.			on failure setting errno to an appropriate value.
	.Pp			.Pp
	The			The
	Show All 11 Lines