annotate xml/syslog2iptables.in @ 12:c2a2e35a85ac

final documentation, rpm builds properly
author carl
date Sat, 17 Dec 2005 16:17:09 -0800
parents a9b52f657f08
children 2a7161b03b94
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
11
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
1 <reference>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
2 <title>@PACKAGE@</title>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
3 <partintro>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
4 <title>Packages</title>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
5 <para>The various source and binary packages are available at <ulink
12
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
6 url="http://www.five-ten-sg.com/@PACKAGE@/packages">http://www.five-ten-sg.com/@PACKAGE@/packages</ulink>
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
7 The most recent documentation is available at <ulink
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
8 url="http://www.five-ten-sg.com/@PACKAGE@/">http://www.five-ten-sg.com/@PACKAGE@/</ulink>
11
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
9 </para>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
10 </partintro>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
11
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
12 <refentry id="@PACKAGE@.1">
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
13 <refentryinfo>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
14 <date>2005-12-15</date>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
15 </refentryinfo>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
16
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
17 <refmeta>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
18 <refentrytitle>@PACKAGE@</refentrytitle>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
19 <manvolnum>1</manvolnum>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
20 <refmiscinfo>@PACKAGE@ @VERSION@</refmiscinfo>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
21 </refmeta>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
22
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
23 <refnamediv id='name.1'>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
24 <refname>@PACKAGE@</refname>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
25 <refpurpose>a simple adaptive firewall</refpurpose>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
26 </refnamediv>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
27
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
28 <refsynopsisdiv id='synopsis.1'>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
29 <title>Synopsis</title>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
30 <cmdsynopsis>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
31 <command>@PACKAGE@</command>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
32 <arg><option>-c</option></arg>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
33 <arg><option>-d <replaceable class="parameter">n</replaceable></option></arg>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
34 </cmdsynopsis>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
35 </refsynopsisdiv>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
36
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
37 <refsect1 id='description.1'>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
38 <title>Description</title>
12
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
39
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
40 <para><command>@PACKAGE@</command> is a simple adaptive firewall. It
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
41 maintains the INPUT chain of the <citerefentry>
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
42 <refentrytitle>iptables</refentrytitle> <manvolnum>1</manvolnum>
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
43 </citerefentry> firewall set based on syslog entries. These syslog
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
44 entries are typically generated by your hardware firewall, but they
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
45 could come from any source. Any syslog entry that contains a host name
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
46 or ip address can be used as input to this package.</para>
11
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
47
12
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
48 <para>The <citerefentry> <refentrytitle>@PACKAGE@.conf</refentrytitle>
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
49 <manvolnum>5</manvolnum> </citerefentry> file specifies the syslog files
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
50 to be monitored, and the regular expressions (<citerefentry>
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
51 <refentrytitle>regex</refentrytitle> <manvolnum>7</manvolnum>
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
52 </citerefentry>) to be applied to new lines in those files. Each
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
53 regular expression needs an index to specify the matching substring that
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
54 contains either an ip address or host name, and a bucket count which is
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
55 added to the leaky bucket for that ip address when a matching line is
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
56 read from that syslog file.</para>
11
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
57
12
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
58 <para>Each ip address has an associated leaky bucket, which leaks one
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
59 token per second. Once the bucket contains more than a configurable
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
60 threshold number of tokens, that ip address is added to the INPUT chain
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
61 with a DROP target. When the bucket is drained to zero, that ip address
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
62 is removed from the INPUT chain.</para>
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
63
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
64 <para>The discussion has focused on syslog files, but any ascii text
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
65 file can be used, so long as some other process appends lines to that
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
66 file, and those lines containing hostname or ip addresses can be matched
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
67 with some regular expression.</para>
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
68
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
69 <para>Considering syslog files in particular, these are normally rotated
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
70 via logrotate. <command>@PACKAGE@</command> properly detects and
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
71 handles this case by closing the old file, and reopening the newly
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
72 created file.</para>
11
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
73 </refsect1>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
74
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
75 <refsect1 id='options.1'>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
76 <title>Options</title>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
77 <variablelist>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
78 <varlistentry>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
79 <term>-c</term>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
80 <listitem>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
81 <para>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
82 Load the configuration file, print a cannonical form
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
83 of the configuration on stdout, and exit.
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
84 </para>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
85 </listitem>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
86 </varlistentry>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
87 <varlistentry>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
88 <term>-d <replaceable class="parameter">n</replaceable></term>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
89 <listitem>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
90 <para>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
91 Set the debug level to <replaceable class="parameter">n</replaceable>.
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
92 </para>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
93 </listitem>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
94 </varlistentry>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
95 </variablelist>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
96 </refsect1>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
97
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
98 <refsect1>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
99 <title>Usage</title>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
100 <para><command>@PACKAGE@</command> -d 2</para>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
101 </refsect1>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
102
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
103 <refsect1>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
104 <title>Configuration</title>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
105 <para>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
106 The configuration file is documented in <citerefentry>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
107 <refentrytitle>@PACKAGE@.conf</refentrytitle> <manvolnum>5</manvolnum>
12
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
108 </citerefentry>. Any change to the config file will cause it to be
c2a2e35a85ac final documentation, rpm builds properly
carl
parents: 11
diff changeset
109 reloaded within three minutes.
11
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
110 </para>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
111 </refsect1>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
112
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
113 <refsect1>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
114 <title>Copyright</title>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
115 <para>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
116 Copyright (C) 2005 by 510 Software Group &lt;carl@five-ten-sg.com&gt;
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
117 </para>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
118 <para>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
119 This program is free software; you can redistribute it and/or modify it
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
120 under the terms of the GNU General Public License as published by the
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
121 Free Software Foundation; either version 2, or (at your option) any
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
122 later version.
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
123 </para>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
124 <para>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
125 You should have received a copy of the GNU General Public License along
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
126 with this program; see the file COPYING. If not, please write to the
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
127 Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
128 </para>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
129 </refsect1>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
130 </refentry>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
131
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
132
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
133 <refentry id="@PACKAGE@.conf.5">
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
134 <refentryinfo>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
135 <date>2005-12-15</date>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
136 </refentryinfo>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
137
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
138 <refmeta>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
139 <refentrytitle>@PACKAGE@.conf</refentrytitle>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
140 <manvolnum>5</manvolnum>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
141 <refmiscinfo>@PACKAGE@ @VERSION@</refmiscinfo>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
142 </refmeta>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
143
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
144 <refnamediv id='name.5'>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
145 <refname>@PACKAGE@.conf</refname>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
146 <refpurpose>configuration file for @PACKAGE@</refpurpose>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
147 </refnamediv>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
148
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
149 <refsynopsisdiv id='synopsis.5'>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
150 <title>Synopsis</title>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
151 <cmdsynopsis>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
152 <command>@PACKAGE@.conf</command>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
153 </cmdsynopsis>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
154 </refsynopsisdiv>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
155
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
156 <refsect1 id='description.5'>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
157 <title>Description</title>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
158 <para>The <command>@PACKAGE@.conf</command> configuration file is
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
159 specified by this partial bnf description.</para>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
160
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
161 <literallayout class="monospaced"><![CDATA[
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
162 CONFIG := THRESHOLD IGNORE {FILE}+
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
163 THRESHOLD := "threshold" THRESHOLD-INTEGER-VALUE ";"
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
164 IGNORE := "ignore" "{" IG-SINGLE+ "};"
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
165 IG-SINGLE := IP-ADDRESS "/" CIDR-BITS ";"
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
166 FILE := "file" FILENAME "{" PATTERN+ "};"
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
167 PATTERN := "pattern" REGULAR-EXPRESSION "{" {INDEX | BUCKET}+ "};"
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
168 INDEX := "index" REGEX-INTEGER-VALUE ";"
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
169 BUCKET := "bucket" BUCKET-ADD-INTEGER-VALUE ";"]]></literallayout>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
170 </refsect1>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
171
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
172 <refsect1 id='sample.5'>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
173 <title>Sample</title>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
174 <literallayout class="monospaced"><![CDATA[
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
175 threshold 550;
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
176
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
177 ignore {
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
178 127.0.0.0/8; // localhost
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
179 };
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
180
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
181 file "/var/log/cisco.log" {
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
182 pattern "Internet_Firewall denied (tcp|udp) ([^(]*)" {
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
183 index 2; // zero based
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
184 bucket 200;
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
185 };
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
186 };
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
187
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
188 file "/var/log/secure" {
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
189 pattern "sshd.*Failed password .* from ::ffff:(.*) port" {
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
190 index 1; // zero based
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
191 bucket 400;
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
192 };
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
193 pattern "sshd.*Failed password .* from (.*) port" {
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
194 index 1; // zero based
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
195 bucket 400;
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
196 };
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
197 };]]></literallayout>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
198 </refsect1>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
199
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
200 </refentry>
a9b52f657f08 finish coding 1.0 version
carl
parents:
diff changeset
201 </reference>