contrib/blacklist/bin/blacklistd.conf.5

   1 .\" $NetBSD: blacklistd.conf.5,v 1.7 2017/06/07 13:50:57 wiz 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 June 5, 2017
  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 file contains configuration entries for
  40 .Xr blacklistd 8
  41 in a fashion similar to
  42 .Xr inetd.conf 5 .
  43 Only one entry per line is permitted.
  44 Every entry must have all fields populated.
  45 Each field can be separated by a tab or a space.
  46 Comments are denoted by a
  47 .Dq #
  48 at the beginning of a line.
  49 .Pp
  50 There are two kinds of configuration lines,
  51 .Va local
  52 and
  53 .Va remote .
  54 By default, configuration lines are
  55 .Va local ,
  56 i.e. the address specified refers to the addresses on the local machine.
  57 To switch to between
  58 .Va local
  59 and
  60 .Va remote
  61 configuration lines you can specify the stanzas:
  62 .Dq [local]
  63 and
  64 .Dq [remote] .
  65 .Pp
  66 On
  67 .Va local
  68 and
  69 .Va remote
  70 lines
  71 .Dq *
  72 means use the default, or wildcard match.
  73 In addition, for
  74 .Va remote
  75 lines
  76 .Dq =
  77 means use the values from the matched
  78 .Va local
  79 configuration line.
  80 .Pp
  81 The first four fields,
  82 .Va location ,
  83 .Va type ,
  84 .Va proto ,
  85 and
  86 .Va owner
  87 are used to match the
  88 .Va local
  89 or
  90 .Va remote
  91 addresses, whereas the last 3 fields
  92 .Va name ,
  93 .Va nfail ,
  94 and
  95 .Va disable
  96 are used to modify the filtering action.
  97 .Pp
  98 The first field denotes the
  99 .Va location
 100 as an address, mask, and port.
 101 The syntax for the
 102 .Va location
 103 is:
 104 .Bd -literal -offset indent
 105         [<address>|<interface>][/<mask>][:<port>]
 106 .Ed
 107 .Pp
 108 The
 109 .Dv address
 110 can be an IPv4 address in numeric format, an IPv6 address
 111 in numeric format and enclosed by square brackets, or an interface name.
 112 Mask modifiers are not allowed on interfaces because interfaces
 113 can have multiple addresses in different protocols where the mask has a different
 114 size.
 115 .Pp
 116 The
 117 .Dv mask
 118 is always numeric, but the
 119 .Dv port
 120 can be either numeric or symbolic.
 121 .Pp
 122 The second field is the socket
 123 .Va type :
 124 .Dv stream ,
 125 .Dv dgram ,
 126 or numeric.
 127 The third field is the
 128 .Va prococol :
 129 .Dv tcp ,
 130 .Dv udp ,
 131 .Dv tcp6 ,
 132 .Dv udp6 ,
 133 or numeric.
 134 The fourth file is the effective user
 135 .Va ( owner )
 136 of the daemon process reporting the event,
 137 either as a username or a userid.
 138 .Pp
 139 The rest of the fields are controlling the behavior of the filter.
 140 .Pp
 141 The
 142 .Va name
 143 field, is the name of the packet filter rule to be used.
 144 If the
 145 .Va name
 146 starts with a
 147 .Dq - ,
 148 then the default rulename is prepended to the given name.
 149 If the
 150 .Dv name
 151 contains a
 152 .Dq / ,
 153 the remaining portion of the name is interpreted as the mask to be
 154 applied to the address specified in the rule, causing a single rule violation to
 155 block the entire subnet for the configured prefix.
 156 .Pp
 157 The
 158 .Va nfail
 159 field contains the number of failed attempts before access is blocked,
 160 defaulting to
 161 .Dq *
 162 meaning never, and the last field
 163 .Va disable
 164 specifies the amount of time since the last access that the blocking
 165 rule should be active, defaulting to
 166 .Dq *
 167 meaning forever.
 168 The default unit for
 169 .Va disable
 170 is seconds, but one can specify suffixes for different units, such as
 171 .Dq m
 172 for minutes
 173 .Dq h
 174 for hours and
 175 .Dq d
 176 for days.
 177 .Pp
 178 Matching is done first by checking the
 179 .Va local
 180 rules individually, in the order of the most specific to the least specific.
 181 If a match is found, then the
 182 .Va remote
 183 rules are applied.
 184 The
 185 .Va name ,
 186 .Va nfail ,
 187 and
 188 .Va disable
 189 fields can be altered by the
 190 .Va remote
 191 rule that matched.
 192 .Pp
 193 The
 194 .Va remote
 195 rules can be used for whitelisting specific addresses, changing the mask
 196 size, the rule that the packet filter uses, the number of failed attempts,
 197 or the block duration.
 198 .Sh FILES
 199 .Bl -tag -width /etc/blacklistd.conf -compact
 200 .It Pa /etc/blacklistd.conf
 201 Configuration file.
 202 .El
 203 .Sh EXAMPLES
 204 .Bd -literal -offset 8n
 205 # Block ssh, after 3 attempts for 6 hours on the bnx0 interface
 206 [local]
 207 # location      type    proto   owner   name    nfail   duration
 208 bnx0:ssh        *       *       *       *       3       6h
 209 [remote]
 210 # Never block 1.2.3.4
 211 1.2.3.4:ssh     *       *       *       *       *       *
 212 # For addresses coming from 8.8.0.0/16 block class C networks instead
 213 # individual hosts, but keep the rest of the blocking parameters the same.
 214 8.8.0.0/16:ssh  *       *       *       /24     =       =
 215 .Ed
 216 .Sh SEE ALSO
 217 .Xr blacklistctl 8 ,
 218 .Xr blacklistd 8
 219 .Sh HISTORY
 220 .Nm
 221 first appeared in
 222 .Nx 7 .
 223 .Fx
 224 support for
 225 .Nm
 226 was implemented in
 227 .Fx 11 .
 228 .Sh AUTHORS
 229 .An Christos Zoulas