Import r143 from https://svn.physik.uni-augsburg.de/svn/fail2ban-p2p/trunk

doc/INSTALL

@@ -0,0 +1,117 @@
+If packages for your distribution are available use them. If not use the
+manual installation described below.
+
+== Depencies ==
+
+ * python
+ * python-m2crypt
+ * python-argparse
+
+== Installation on Debian based systems ==
+
+ * Download the latest deb package
+ * install depencies: apt-get install python-m2crypt python-argparse
+ * install fail2ban-p2p: dpkg -i fail2ban-p2p-<version>.deb
+
+== Manual instalation ==
+
+Download the latest tarball and extract it. After changing into the
+fail2ban-p2p directory execute "python setup.py install", this will
+install fail2ban-p2p.py and fail2ban-p2p-client.py to /usr/local/bin.
+Modules will be installed to /usr/share/fail2ban-p2p/fail2ban-p2p.
+
+== Configuration ==
+
+The default configuration directory is /etc/fail2ban-p2p. You can specify
+another directory with the -c command line option. See the CONFIG file in
+this directory for a explanation of all config options.
+
+== Setup ==
+
+In order to use fail2ban-p2p you need to create a keypair for your node,
+exchange public keys with at least one friend and setup fail2ban to work
+with fail2ban-p2p.
+
+1.) Creating a keypair for your node and exchange it with friend(s)
+
+If no keypair is found in the configuration directory it will be created
+at the first start of fail2ban-p2p.py or when using the -K command line
+option. This needs to be done by a user who has write permissions in
+the configuration directory.
+
+Two files are created: private.pem and public.pem. private.pem is your
+private key, keep this secret. public.pem needs to be shared with at least
+one friend. But before you share it add something like this in public.pem
+before the key:
+
+address = 1.2.3.4
+port = 1337
+trustlevel = 80
+
+This is the information how your node is reachable.
+
+address		Use your IP address or dns name here.
+                To listen on all addresses use 0.0.0.0
+port		The port your node listens ons (see fail2ban-p2p.conf)
+trustlevel	This is something your friend is allowed to edit
+		to give you more or less trust. Its a percentage, so use
+		something between 0 and 100.
+
+Now send the edited public.pem to your friend(s). For every friend that you
+want to add get his private.pem and place it in <config dir>/friends. Rename
+the file to the name you want to use for this friend.
+
+2.) Integration with fail2ban
+
+To properly work and be able to exchange information with the fail2ban-daemon
+you need to integrate fail2ban and fail2ban-p2p. Information about attackers
+needs to be exchanged in two directions:
+
+2.1.) From fail2ban-p2p to fail2ban
+
+Fail2ban gets its information about attackers by watching the fail2ban-p2p
+logfile. To setup fail2ban to watch the fail2ban-p2p log file do the following:
+ 
+ * Make fail2ban-p2p log into /var/log/fail2ban-p2p.log (this is the default)
+ * Add a jail for fail2ban-p2p like this in /etc/fail2ban/jails.conf:
+
+   [ssh-p2p]
+   enabled = true
+   port    = ssh
+   filter  = sshd-p2p
+   logpath  = /var/log/fail2ban-p2p.log
+   bantime = 120
+   findtime = 120
+   maxretry = 1
+
+   See the fail2ban manual for explanation of these options. You probably
+   want to increase the bantime. It is important to leave maxretry at 1 (block
+   a host after 1 entry for it was found in /var/log/fail2ban-p2p.log).
+
+ * Add a filter sshd-p2p.conf in /etc/fail2ban/filter.d/sshd-p2p.conf
+
+   [Definition]
+   failregex = ^(.*)BAN(\t)<HOST>*$
+
+2.2.) From fail2ban to fail2ban-p2p
+
+ * Setup an action to execute "fail2ban-p2p-client.py -b <ip>" to sent
+   the attacker IP from fail2ban to fail2ban-p2p.
+   For an example see doc/fail2ban/action.d/fail2ban-p2p.conf.
+   You might want to correct the path to client.py and also specify a
+   configuration directory for fail2ban-p2p with the -c option if you do
+   use a custom config directory.
+
+ * add this action to a jail, e.g. for the predefined ssh jail in jail.conf:
+
+  [ssh]
+  enabled  = true
+  port     = ssh
+  filter   = sshd
+  logpath  = /var/log/auth.log
+  action   = iptables[name=SSH, port=ssh, protocol=tcp]
+             fail2ban-p2p[name=SSH]
+  maxretry = 2
+
+  This will ban the offending ip with the iptables action and also send
+  a notice to fail2ban-p2p that fail2ban has blocked an ip.