1ip-sentinel(8) System Manager's Manual ip-sentinel(8)
2
6 ip-sentinel - keeps your IP space clean
7
9 ip-sentinel [--user|-u username] [--group|-g groupname] [--chroot|-r
10 dir] [--ipfile|-i file] [--pidfile|-p file] [--logfile|-l file]
11 [--errfile|-e file] [--mac mac] [--llmac mac] [--direction dir]
12 [--action program] [--nofork|-n] [--help|-h] [--version] interface
13
15 ip-sentinel starts a daemon which tries to prevent unauthorized usage
16 of IPs within an ethernet broadcastdomain by answering ARP requests.
17 After receiving such a faked reply, the requesting party stores the MAC
18 address in its ARP-table and will send future packets to this invalid
19 MAC, rendering the IP unreachable.
20 After startup it opens its logfiles, goes into a chroot jail, drops
22 privileges and forks itself into background by default. The parameters
23 of these operations can by changed by the options described below.
24 Warning: with an uncareful configuration, ip-sentinel can bring down
26 the entire network and your physical presence at the ip-sentinel
27 machine and/or the switch will be required to fix it. Some switches can
28 show an unexpected behavior are even crash when the special 802.* mac-
29 addresses will be used.
30
32 --user|-u username and --group|-g groupname
33 After doing basical initializations, the program will drop its
34 privilegies by changing its user and group ID. The username and
35 groupname parameters determine these new IDs and must be an
36 alphanumeric username/groupname or a numeric uid/gid.
37 Attention: When having a dietlibc-compiled version in a system
39 which uses remote NSS (e.g. LDAP, NIS) to make passwd-lookups,
40 you will have to use numeric IDs.
41 --chroot|-r dirname
43 Specifies the directory where the program shall go into and call
44 chroot() after finishing its initialization. By default it is
45 the homedirectory of the user specified with the --user option.
46 --ipfile|-i filename
48 Sets the name of the configuration file which contains the list
49 of forbidden IPs. This name is relative to the chroot and is
50 ips.cfg by default. This file will be reread automatically after
51 changes.
52 --pidfile|-p filename
54 Sets the file where the pid of the daemon will be written into.
55 This filename is relative to the root-filesystem and is
56 /var/run/ip-sentinel.run by default.
57 --logfile|-l filename
59 Sets the file where normal operations will be logged. Normal
60 operations are e.g. an ARP-reply for a forbidden IP. This file‐
61 name is relative to the root-filesystem and /var/log/ip-sen‐
62 tinel.out by default.
63 --errfile|-e filename
65 Sets the file where error-conditions will be logged. Error-con‐
66 ditions are e.g. detected DOS attacks (bombing the ip-sentinel
67 with ARP-requests) or errors in the configuration file. This
68 filename is relative to the root-filesystem and /var/log/ip-sen‐
69 tinel.err by default.
70 --nofork|-n
72 Prevents daemon from going into background after initialization.
73 This option may be useful when using advanced init-concepts like
74 minit (http://www.fefe.de/minit/).
75 --direction dir
77 ip-sentinel can answer both requests asking for an intruder's
78 address, and requests coming from an intruder asking for offi‐
79 cial addresses. This parameter specifies which requests shall be
80 answered. Possible values are FROM (requests from intruders), TO
81 (requests to intruders) and BOTH. The current default value is
82 TO, but will probably change to BOTH in future versions.
83 --mac mac
85 Use mac as the default faked mac-address; see below for possible
86 values. This parameter can be overriden in the ipfile for each
87 questionable IP. The default value is RANDOM.
88 --llmac mac
90 Specifies the mac-address which will be used in the link-level
91 headers when answering requests from intruders. Additionally to
92 the values described below, ip-sentinel understands the SAME
93 string, which means that the address from the ARP-header will be
94 used. When not using the FROM or BOTH directions, the assigned
95 value will not have any effect. The default is LOCAL.
96 --poison
98 When an intruder sends a request from a registered ip address
99 and this option is set, ip-sentinel will send ARP replies which
100 are poisoning this ip. When the @!srcmac syntax is used for the
101 questionable ip, the srcmac is used as the is-at mac. Else, the
102 mac specified by the --mac option is used.
103 This option takes an affect only when --destination BOTH or FROM
105 is specified.
106 --action program
108 Execute program when a faked ARP reply will be generated. It
109 will be called with 6 arguments:
110 · type 0 when an intruder sent the request, 1 when a protected
112 IP was requested and -1 else (should never happen)
113 · spa the protocol address (IP) of the source
115 · sha the hardware address (MAC) of the source
117 · tpa the protocol address (IP) of the target
119 · tha the hardware address (MAC) of the target
121 · mac the generated MAC address
123 The program will be executed only without evaluating its return
125 value or something else. Please note, that the program will be
126 executed in the chroot with restricted rights.
127 --help|-h
129 Prints help message and exits.
130 --version
132 Prints the version of the program and exits.
133 interface
135 Specifies the network-interface where ip-sentinel listens for
136 ARP-requests and sends ARP-replies. It is a name like "eth0";
137 aliases like "eth0:1" are not possible.
138
140 The location of the configfile is relatively to the choosen chroot-
141 directory. Its default is determined at compilation time but it can be
142 overriden by the --ipfile option.
143 The content of this file has the following syntax:
145 ip [mac]
147 Specifies an IP which shall be blocked. "Blocked" means that
148 ARP-replies will be generated telling that the IP address ip has
149 the MAC mac. When the MAC parameter is not given, a random one
150 will be choosen.
151 Attention: Assigning a MAC in a switched environment will not
153 have the desired effect, because the switch will be confused
154 when receiving ARP-replies for the same IP on different ports
155 (this one of the bad-host and this one of the ip-sentinel host).
156 Examples are: "192.168.42.23 11:22:33:44:55:66" or "10.0.0.0".
158 ip@[!]srcmac [mac]
160 Similarly to above, but when receiving ARP-requests, the entire
161 sender-address (IP and MAC) will be compared against the ip and
162 srcmac values. This setting affects packets from intruders only;
163 ip-sentinel will not generate replies when ip is requested.
164 When the srcmac is negated with "!", only addresses from this ip
166 which are not having this mac will be matching.
167 Examples are: "10.0.0.1@0:1:2:3:4:5" or "10.0.0.2@!a:b:c:d:e:f".
169 *@srcmac [mac]
171 Every host using the srcmac will be blocked unless there is a
172 matching ip@srcmac specification. This option does not support
173 '!' modifiers.
174 net/mask [mac]
176 net/mask@[!]srcmac [mac]
177 Specifies that IPs of an entiry network shall be blocked. See
178 above for the meaning of "blocked". It is possible to specify a
179 MAC address; else a random one will be generated.
180 Examples are: "169.0.0.0/8", "192.168.8.15/255.255.65.31" or
182 "192.168.23.42/26 a:b:c:d:e:f".
183 !ip
185 !ip@[!]srcmac
186 The given IP address ip will be ignored. By default, any not
187 specified address will be ignored but when having blocked net‐
188 masks it may be usefully to allow certain IPs.
189 An example is: "!192.168.23.42"
191 !net/mask
193 !net/mask@[!]srcmac
194 Tells that IPs of the given network shall be ignored.
195 Examples are: "!192.168.1.0/255.255.255.0" or "!0.0.0.0/0" (the
197 default).
198 # comment (and empty lines)
200 A comment; will be ignored
201 To be switch-friendly, there are only a few random MACs possible which
204 are having the format "de:ad:be:ef:00:XX". Within a short timespan only
205 32 values are possible for XX.
206 When having overlapping networks and/or single IPs, this one with the
208 most specified netmask (count of 1's) takes precedence. When netmasks
209 are equal, networks which are using the "@srcmac" or "@!srcmac" syntax
210 are taking precedence over those without source-macs. This "@..." rule
211 does not apply to IPs. The behavior is unspecified when having overlap‐
212 ping networks with the same count of 1's and "@..." specification, or
213 when having duplicate IPs.
214 PERFORMANCE
217 The lookup of single IPs has a complexity of O(log n) and this of net‐
218 masks a complexity of O(n).
219 SPECIAL MAC ADDRESSES
222 Beside the usual hex-octets-delimited-by-colons mac addresses, ip-sen‐
223 tinel understands some special strings both on the commandline and in
224 the configuration file:
225 LOCAL expands to the mac-address of the used interface
227 RANDOM means a random mac-address which is newly calculated on every
229 usage
230 802.1d expands to 01:80:C2:00:00:00 which is the "Bridge Group
232 Address".
233 802.3x expands to 01:80:C2:00:00:01 which is the "IEEE Std. 802.3x Full
235 Duplex PAUSE operation". This MAC address will be blocked by a
236 lot of switches and will probably become the default in future
237 versions.
238 The 802.* addresses are having a special meaning for some switches and
240 packets having them as destination-address will be dropped by the
241 switch instead of flooding all ports. But it depends on the used switch
242 how/if these macs are honored.
243 Some switches can show an unexpected behavior are even crash if the
245 special 802.* mac-addresses will be used.
246 RANGES
248 Except in comments, it is possible to specify ranges everywhere in the
249 configuration file. These ranges are having the format "{from-to}" or
250 "{item1,item2,...,itemN}". The first format includes any number begin‐
251 ning at "from" till "to" (inclusive), while the latter format expands
252 to the listed items only. The expansion happens on a line-level and it
253 is possible to use more than one range per line, so that
254 192.168.0.{1-3} 0:0:0:0:0:1
256 192.168.1.{1,3} 0:0:0:0:0:2
257 192.168.{2,4}.{1-3} 0:0:0:0:0:3
258 is the same like writing
260 192.168.0.1 0:0:0:0:0:1
262 192.168.0.2 0:0:0:0:0:1
263 192.168.0.3 0:0:0:0:0:1
264 192.168.1.1 0:0:0:0:0:1
265 192.168.1.3 0:0:0:0:0:1
266 192.168.2.1 0:0:0:0:0:3
267 192.168.2.2 0:0:0:0:0:3
268 192.168.2.3 0:0:0:0:0:3
269 192.168.4.1 0:0:0:0:0:3
270 192.168.4.2 0:0:0:0:0:3
271 192.168.4.3 0:0:0:0:0:3
272 Because there can be created very much entries with a single line (e.g.
274 "{0-255}.{0-255}.{0-255}.{0-255}" would cover the entire IPv4 inter‐
275 net), ranges should be used sparely. When possible, large ranges should
276 be expressed with netmasks.
277 EXAMPLE
280 0.0.0.0/0 ## Block anything
281 !192.168.0.0/24 ## Allow IPs of the form 192.168.0.*
282 192.168.0.0 ## but block 192.168.0.0
283 192.168.0.1 a:b:c:d:e:f ## use a special mac for 192.168.0.1
284 192.168.0.2 802.1d ## and 01:80:C2:00:00:00 for 192.168.0.2
285 10.0.0.1@a:a:a:a:a:a
286 10.0.0.2@!1:1:1:1:1:1
287 *@b:b:b:b:b:b ## block MAC b:b:b:b:b:b regardless of the IP
288 This setup will not send ARP-replies for the IPs 192.168.0.{3-255} but
290 when a host tries to use e.g. 169.254.145.213, ip-sentinel will tell
291 that this IP has a MAC of "de:ad:be:ef:00:XX".
292 When an intruder is at "10.0.0.1" and uses the mac "a:a:a:a:a:a:", a
294 faked reply will be generated. Users at the same ip but another mac
295 will be ignored.
296 In opposite, users with ip "10.0.0.2" and mac "1:1:1:1:1:1" will be
298 ignored but intruders with other macs (e.g. "2:2:2:2:2:2") are getting
299 faked replies. When --poision is used, ip-sentinel will generate a
300 "10.0.0.2 is at 1:1:1:1:1:1" arp-reply to a broad address.
301
303 RFC 826, IEEE Std 802.1D
304
306 Enrico Scholz <enrico.scholz@informatik.tu-chemnitz.de>
307ip-sentinel 0.11 Dec 15 2004 ip-sentinel(8)