fail2ban-p2p/doc/INSTALL

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.