The following text is the file README from the package.
Eble vi volas legi la Esperantan version.

pam_sieĝo

This is a pam module that helps to defend your castle, by closing the gate for visitors that repeatedly unsuccesfully try to come in.

This program is licensed GNU GPL (see COPYING).

The language is Esperanto. To start using it, delete the line #define UTF8 1 in pam_siegho.c (i suppose you want the non UTF-8 version, without the strange letters ĉ, ĝ, ĥ, ĵ, ŝ and ŭ), and write:

$make $su -c 'cp pam_siegho.so /lib/security' # location of the pam libraries

Then add a line for the services for which you want to use attack-protection to the pam comfiguration file (/etc/pam.d/service or /etc/pam.conf) auth require pam_siegho.so or auth requisite pam_siegho.so. If you use require, pam will always ask for a password (or another way of authentication), whether or not the visitor already tried too many times; with requisite, the visitor will immediately be barred out (en the latter case, be sure to place the line before the other authentication methods, like a password). An example:





auth    requisite pam_siegho.so

auth    required  pam_unix.so

account required  pam_unix.so

session required  pam_unix.so



You should also make a ruleset for pam_siegho in /etc/siegho (you can
change the default location in pam_siegho.c or by adding an argument
regularo=path to the module line in the pam configuration). The
regularo can be a normal file or a folder. If it is a folder, the
file with the name of the pam service in the folder will be used, or
aliaj (others) if it doesn't exist. The settings you can make are
the following (if you don't specify a setting, the values given here
will be used; lines starting with # are comments):



notlibro=/var/log/sieĝo

# Where to remember the timo (fear)




rekonajho=armeo

# How to recognise the visitor (not all services define everything;

# you cannot use undefined rekonajhoj). This is a list of

# recognisation things, separated by comma's (,). The possible

# rekonajhoj are:

#    * anonco (USER: who the visitor pretends to be

#    * militisto (RUSER: name of the visitor on the remote computer)

#    * armeo (RHOST: DNS name of the coputer of the visitor)

# You should be aware that a visitor can pretend whatever he wants for

# anonco, en maybe also for militisto. The armeo (DNS name) can change

# from time to time with dynamic IP addresses.

# So, if you want to count the tries of one man from one coputer, to

# come in as one user, write:

#rekonajho=anonco,militisto,armeo





timemo=1m
# How long to remember tries (s=seconds, m=minutes, h=hours, t=days).




limo=10
# Number of tries.




dauro=1t
# Time to ban out a visitor if the timo exceeds the limo.




ago=
# Action when the visitor is barred out.
# To send an e-mail, use:
#ago=echo "$MILITISTO@$ARMEO --> $ANONCO tried too many times to get in" | mail -s "barred out $ARMEO" root




Well, how does this work?

For every visitor, the time of the last try and the timo (fear) is
remembered (in the notlibro). Every time a visitor tries to get in
(when pam is called), the timo increases by one unit , and decreases
by one unit for each time timemo passed since the last try. If after
that the timo exceeds the limo, the visitor will not be able to come
in and the ago will be executed. If the visitor, while he is barred
out, tries to come in before the dauro passed, the time of the last
try is updated (so he will have to wait the whole dauro again), but
the ago isn't done again. After a successful login, the guard becomes
quiet about that visitor again (the timo becomes 0).

We'll look at an example: rekonajho is armeo ago is to send an email
to root, timemo is one minute, limo is 10 en dauro is one day.


good.org tries to come in

timo for good.org becomes 1
visitor is accepted (he can try)


good.org gives a good password

timo for good.org is reset to 0


good.org tries to come in

timo for good.org becomes 1
good.org misses about the password


good.org tries again to come in

timo for good.org becomes 2
good.org can try


good.org gives a good password

timo for good.org becomes 0


bad.org tries to come in

timo for bad.org becomes 1
bad.org can try to come in


bad.org gives a bad password
bad.org tries again

timo for bad.org becomes 2
bad.org can try


bad.org tries again

timo for bad.org becomes 3
bad.org can try



---after two minutes---

bad.org tries again

timo for bad.org becomes 2 (timemo passed two times (-2) and a new try (+1))
bad.org can try


bad.org tries again

timo for bad.org becomes 3
bad.org can try


...
bad.org tries again

timo for bad.org becomes 10
bad.org can try


bad.org tries again

timo for bad.org becomes 11
visitor is barred out
root receives an e-mail



---after half a day---

bad.org tries again

timo for bad.org becomes 12
visitor remains barred out



---after half a day---

bad.org tries again

timo for bad.org becomes 13
visitor remains barred out (because the last try was just half a day ago)



---after two days---

bad.org tries again

timo for bad.org is already 0, becomes 1
bad.org can try again





Ideas for use.

A way to use this is to protect you ssh (or another) server against
attacks from people who try to guess a password. Set rekonajho to
armeo (the remote host). With ipset (see http://ipset.netfilter.org/),
you can then have an action to add the remote host to an ip set with
timeout one day (or so), and in your iptable rules, add a rule which
blocks packets from that addresses.


I found a bug / want to contact the author

If you found a bug, have ideas for improvements, really want to tell
some story related to this little program, ... contact the author (por
program changes, patches are welcome, of course): Maarten Deprez
<maartendeprez at users dot sourceforge dot net>.