View source for HOWTO Upgrade from 0.6 to 0.8

== Upgrade guide from 0.6 to 0.8 ==

This guide explains how to upgrade from a previous 0.6 installation to 0.8.

=== Changes ===

There are two important changes from the user's point of view. First, 0.8 is now composed of two independent applications: fail2ban-client and fail2ban-server. 0.6 uses a "monolithic" design. Second, 0.8 has multiple configuration files where 0.6 uses only one.

There are a lot of new features and changes. 0.8 is almost a complete rewrite from 0.6. For more information, take a look a the [[ChangeLog]] and [[Features]].

Another change that can be worth to notify is the fact that mail notifications are replaced by actions in 0.8. We will look at this more deeply in the above sections.

=== The concept of jail ===

Version 0.8 introduces the concept of a jail. A jail is the combination of a filter and one or more action scripts. Look at the manual for more information about this. A jail in 0.8 is quite similar to a section in the configuration file of 0.6. Filters are located in ''/etc/fail2ban/filter.d'' and actions in ''/etc/fail2ban/action.d''.

Let's take an example.

 [SSH]
 enabled = true
 logfile = /var/log/secure
 port = ssh
 protocol = tcp
 fwstart = iptables -N fail2ban-%(__name__)s
           iptables -A fail2ban-%(__name__)s -j RETURN
           iptables -I INPUT -p %(protocol)s --dport %(port)s -j fail2ban-%(__name__)s
 fwend = iptables -D INPUT -p %(protocol)s --dport %(port)s -j fail2ban-%(__name__)s
         iptables -F fail2ban-%(__name__)s
         iptables -X fail2ban-%(__name__)s
 fwcheck = iptables -L INPUT | grep -q fail2ban-%(__name__)s
 fwban = iptables -I fail2ban-%(__name__)s 1 -s <ip> -j DROP
 fwunban = iptables -D fail2ban-%(__name__)s -s <ip> -j DROP
 timeregex = \S{3}\s{1,2}\d{1,2} \d{2}:\d{2}:\d{2}
 timepattern = %%b %%d %%H:%%M:%%S
 failregex = : (?:(?:Authentication failure|Failed [-/\w+]+) for(?: [iI](?:llegal|nvalid)
             user)?|[Ii](?:llegal|nvalid) user|ROOT LOGIN REFUSED) .*(?: from|FROM)
             (?:::f{4,6}:)?(?P<host>\S*)

This is a typical section taken from ''fail2ban.conf'' in a 0.6 release.

==== Filter ====

We can now create a filter using the above information. The filter contains regular expressions which should match break-in attempts. Create the file ''/etc/fail2ban/filter.d/sshd.conf'' and edit it with the following content.

 [Definition]
 failregex = Authentication failure for .* from <HOST>
             Failed [-/\w]+ for .* from <HOST>
             ROOT LOGIN REFUSED .* FROM <HOST>
             [iI](?:llegal|nvalid) user .* from <HOST>
 ignoreregex =

As you can see, 0.8 supports multiple regular expressions. This simplifies the creation of new regular expressions. There is no equivalent for '''ignoreregex''' in 0.6. We are done with our filter.

==== Action ====

Now, we need an action file. There is a bit more work to be done here. The '''fw*''' options are simply renamed to '''action*'''. The Python interpolation are replaced here with tags. Some tags are static and some are dynamic. Static tags are defined in '''[Init]''' with default values. Static tags can be overwritten in '''jail.conf'''. We will see this further in this guide. Dynamic tags are passed at runtime by {{Fail2ban}}. This is the case here for '''<ip>'''. Create the file '''/etc/fail2ban/action.d/iptables.conf''' and edit it with the following content.

 [Definition]
 actionstart = iptables -N fail2ban-<name>
               iptables -A fail2ban-<name> -j RETURN
               iptables -I INPUT -p <protocol> --dport <port> -j fail2ban-<name>
 actionstop = iptables -D INPUT -p <protocol> --dport <port> -j fail2ban-<name>
              iptables -F fail2ban-<name>
              iptables -X fail2ban-<name>
 actioncheck = iptables -n -L INPUT | grep -q fail2ban-<name>
 actionban = iptables -I fail2ban-<name> 1 -s <ip> -j DROP
 actionunban = iptables -D fail2ban-<name> -s <ip> -j DROP
 
 [Init]
 name = default
 port = ssh
 protocol = tcp

==== Jail ====

Here we are. Now that you have a filter and an action file, you can create your first jail. Create the file '''/etc/fail2ban/jail.conf''' and add this.

 [SSH]
 enabled  = true
 filter   = sshd
 action   = iptables[name=SSH, port=ssh, protocol=tcp]
            mail-whois[name=SSH, dest=yourmail@mail.com]
 logpath  = /var/log/secure
 maxretry = 5

The '''filter''' option defines which filter must be used. Only one filter is allowed. Here we put the name of the file we created before (without the extension). '''action''' defines one or more action files. As explained before, the static tags can be redefined here. 0.8 does not use Python smtplib anymore for mail notification. This feature is now implemented using action.

'''logpath''' defines the log file to be scanned. In 0.8, '''logpath''' can contain wildcards.

=== And now? ===

This is a short tutorial which should help you getting started. You should probably take a look at the [[MANUAL_0_8|manual]]. The configuration files in ''/etc/fail2ban'' are documented and give you enough information to create your own jails.