1ip-sentinel(8)              System Manager's Manual             ip-sentinel(8)
2
3
4

NAME

6       ip-sentinel - keeps your IP space clean
7

SYNOPSIS

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

DESCRIPTION

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
21       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
25       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

OPTIONS

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
38              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
42       --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
47       --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
53       --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
58       --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
64       --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
71       --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
76       --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
84       --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
89       --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
97       --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
104              This option takes an affect only when --destination BOTH or FROM
105              is specified.
106
107       --action program
108              Execute program when a faked ARP reply  will  be  generated.  It
109              will be called with 6 arguments:
110
111              · type  0  when an intruder sent the request, 1 when a protected
112                IP was requested and -1 else (should never happen)
113
114              · spa the protocol address (IP) of the source
115
116              · sha the hardware address (MAC) of the source
117
118              · tpa the protocol address (IP) of the target
119
120              · tha the hardware address (MAC) of the target
121
122              · mac the generated MAC address
123
124              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
128       --help|-h
129              Prints help message and exits.
130
131       --version
132              Prints the version of the program and exits.
133
134       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

CONFIGURATION FILE

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
144       The content of this file has the following syntax:
145
146       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
152              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
157              Examples are: "192.168.42.23  11:22:33:44:55:66" or "10.0.0.0".
158
159       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
165              When the srcmac is negated with "!", only addresses from this ip
166              which are not having this mac will be matching.
167
168              Examples are: "10.0.0.1@0:1:2:3:4:5" or "10.0.0.2@!a:b:c:d:e:f".
169
170       *@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
175       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
181              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
184       !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
190              An example is: "!192.168.23.42"
191
192       !net/mask
193       !net/mask@[!]srcmac
194              Tells that IPs of the given network shall be ignored.
195
196              Examples  are: "!192.168.1.0/255.255.255.0" or "!0.0.0.0/0" (the
197              default).
198
199       # comment (and empty lines)
200              A comment; will be ignored
201
202
203       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
207       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
215
216   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
220
221   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
226       LOCAL  expands to the mac-address of the used interface
227
228       RANDOM means  a  random  mac-address which is newly calculated on every
229              usage
230
231       802.1d expands  to  01:80:C2:00:00:00  which  is  the   "Bridge   Group
232              Address".
233
234       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
239       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
244       Some  switches  can  show  an unexpected behavior are even crash if the
245       special 802.* mac-addresses will be used.
246
247   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
255       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
259       is the same like writing
260
261       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
273       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
278
279   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
289       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
293       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
297       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

SEE ALSO

303       RFC 826, IEEE Std 802.1D
304

AUTHOR

306       Enrico Scholz <enrico.scholz@informatik.tu-chemnitz.de>
307
308
309
310ip-sentinel 0.11                  Dec 15 2004                   ip-sentinel(8)
Impressum