contrib/blacklist/bin/blacklistd.conf.5

   1 .\" $NetBSD: blacklistd.conf.5,v 1.3 2015/04/30 06:20:43 riz Exp $
   2 .\"
   3 .\" Copyright (c) 2015 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Christos Zoulas.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd April 29, 2015
  31 .Dt BLACKLISTD.CONF 5
  32 .Os
  33 .Sh NAME
  34 .Nm blacklistd.conf
  35 .Nd configuration file format for blacklistd
  36 .Sh DESCRIPTION
  37 The
  38 .Nm
  39 files contains configuration lines for
  40 .Xr blacklistd 8 .
  41 It contains one entry per line, and is similar to
  42 .Xr inetd.conf 5 .
  43 There must be an entry for each field of the configuration file, with
  44 entries for each field separated by a tab or a space.
  45 Comments are denoted by a
  46 .Dq #
  47 at the beginning of a line.
  48 .Pp
  49 There are two kinds of configuration lines,
  50 .Va local
  51 and
  52 .Va remote .
  53 By default, configuration lines are
  54 .Va local ,
  55 i.e. the address specified refers to the addresses on the local machine.
  56 To switch to between
  57 .Va local
  58 and
  59 .Va remote
  60 configuration lines you can specify the stanzas:
  61 .Dq [local]
  62 and
  63 .Dq [remote] .
  64 .Pp
  65 On
  66 .Va local
  67 and
  68 .Va remote
  69 lines
  70 .Dq *
  71 means use the default, or wildcard match.
  72 In addition, for
  73 .Va remote
  74 lines
  75 .Dq =
  76 means use the values from the matched
  77 .Va local
  78 configuration line.
  79 .Pp
  80 The first four fields,
  81 .Va location ,
  82 .Va type ,
  83 .Va proto ,
  84 and
  85 .Va owner
  86 are used to match the
  87 .Va local
  88 or
  89 .Va remote
  90 addresses, whereas the last 3 fields
  91 .Va name ,
  92 .Va nfail ,
  93 and
  94 .Va disable
  95 are used to modify the filtering action.
  96 .Pp
  97 The first field denotes the
  98 .Va location
  99 as an address, mask, and port.
 100 The syntax for the
 101 .Va location
 102 is:
 103 .Bd -literal -offset indent
 104         [<address>|<interface>][/<mask>][:<port>]
 105 .Ed
 106 .Pp
 107 The
 108 .Dv address
 109 can be an IPv4 address in numeric format, an IPv6 address
 110 in numeric format and enclosed by square brackets, or an interface name.
 111 Mask modifiers are not allowed on interfaces because interfaces
 112 have multiple address in different protocols where the mask has a different
 113 size.
 114 .Pp
 115 The
 116 .Dv mask
 117 is always numeric, but the
 118 .Dv port
 119 can be either numeric or symbolic.
 120 .Pp
 121 The second field is the socket
 122 .Va type :
 123 .Dv stream ,
 124 .Dv dgram ,
 125 or numeric.
 126 The third field is the
 127 .Va prococol :
 128 .Dv tcp ,
 129 .Dv udp ,
 130 .Dv tcp6 ,
 131 .Dv udp6 ,
 132 or numeric.
 133 The fourth file is the effective user
 134 .Va ( owner )
 135 of the daemon process reporting the event,
 136 either as a username or a userid.
 137 .Pp
 138 The rest of the fields are controlling the behavior of the filter.
 139 .Pp
 140 The
 141 .Va name
 142 field, is the name of the packet filter rule to be used.
 143 If the
 144 .Va name
 145 starts with a
 146 .Dq - ,
 147 then the default rulename is prepended to the given name.
 148 If the
 149 .Dv name
 150 contains a
 151 .Dq / ,
 152 the remaining portion of the name is interpreted as the mask to be
 153 applied to the address specified in the rule, so one can block whole
 154 subnets for a single rule violation.
 155 .Pp
 156 The
 157 .Va nfail
 158 field contains the number of failed attempts before access is blocked,
 159 defaulting to
 160 .Dq *
 161 meaning never, and the last field
 162 .Va disable
 163 specifies the amount of time since the last access that the blocking
 164 rule should be active, defaulting to
 165 .Dq *
 166 meaning forever.
 167 The default unit for
 168 .Va disable
 169 is seconds, but one can specify suffixes for different units, such as
 170 .Dq m
 171 for minutes
 172 .Dq h
 173 for hours and
 174 .Dq d
 175 for days.
 176 .Pp
 177 Matching is done first by checking the
 178 .Va local
 179 rules one by one, from the most specific to the least specific.
 180 If a match is found, then the
 181 .Va remote
 182 rules are applied, and if a match is found the
 183 .Va name ,
 184 .Va nfail ,
 185 and
 186 .Va disable
 187 fields can be altered by the
 188 .Va remote
 189 rule that matched.
 190 .Pp
 191 The
 192 .Va remote
 193 rules can be used for whitelisting specific addresses, changing the mask
 194 size, or the rule that the packet filter uses, the number of failed attempts,
 195 or the blocked duration.
 196 .Sh FILES
 197 .Bl -tag -width /etc/blacklistd.conf -compact
 198 .It Pa /etc/blacklistd.conf
 199 Configuration file.
 200 .El
 201 .Sh EXAMPLES
 202 .Bd -literal -offset
 203 # Block ssh, after 3 attempts for 6 hours on the bnx0 interface
 204 [local]
 205 # location      type    proto   owner   name    nfail   duration
 206 bnx0:ssh        *       *       *       *       3       6h
 207 [remote]
 208 # Never block 1.2.3.4
 209 1.2.3.4:ssh     *       *       *       *       *       *
 210 # For addresses coming from 8.8.0.0/16 block class C networks instead
 211 # individual hosts, but keep the rest of the blocking parameters the same.
 212 8.8.0.0/16:ssh  *       *       *       /24     =       =
 213 .Ed
 214 .Sh SEE ALSO
 215 .Xr blacklistctl 8 ,
 216 .Xr blacklistd 8
 217 .Sh HISTORY
 218 .Nm
 219 appeared in
 220 .Nx 7 .
 221 .Sh AUTHORS
 222 .An Christos Zoulas