You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Aug 8, 2022. It is now read-only.
project_blurb: "[{{ project_name|capitalize }}]({{ project_url }}) Fail2Ban can do many things but at its core it scans log files and bans IP addresses with too many failed login attempts by adding firewall rules to reject new connections from those IP addresses, for a configurable amount of time."
vol_host_path: "<path to applicationY log directory>",
49
+
desc: "Path to an application log directory with multiple logs.",
50
+
}
37
51
param_usage_include_ports: false
38
52
param_ports:
39
53
param_device_map: false
@@ -51,80 +65,78 @@ optional_block_1: false
51
65
# application setup block
52
66
app_setup_block_enabled: true
53
67
app_setup_block: |
54
-
This docker specific implementation of fail2ban can read an arbitrary number of log files from other containers, monitor them for abuse as a single large entity
55
-
and apply IP bans that will protect ALL docker containers on the host but not the host itself.
56
-
68
+
This docker specific implementation of fail2ban can read an arbitrary number of log files from other containers, monitor them for abuse as a single large entity and apply IP bans that will protect ALL docker containers on the host but not the host itself.
69
+
57
70
To do this it takes advantage of the DOCKER-USER iptables chain that exists in all modern docker installs.
58
-
71
+
59
72
Note: Internal Docker iptables rules are added to the DOCKER chain which is separate to the DOCKER-USER chain and should never be manipulated directly by the user.
60
-
73
+
61
74
Since DOCKER-USER rules are applied before any rules Docker itself creates fail2ban blocks automatically apply to all local native and custom docker bridge networks without risking breaking docker itself.
62
-
63
-
IMPORTANT: Both the DOCKER and DOCKER-USER chains are evaluated BEFORE the FORWARD chain. This is often overlooked by users who expected existing firewall restrictions to
64
-
apply to docker services which they do not resulting in the false assumption that services are protected and private when they are not.
65
-
75
+
76
+
> IMPORTANT: Both the DOCKER and DOCKER-USER chains are evaluated BEFORE the FORWARD chain. This is often overlooked by users who expected existing firewall restrictions to apply to docker services which they do not resulting in the false assumption that services are protected and private when they are not.
77
+
66
78
If none of this make sense to you don't worry you do not need to understand firewalling to make use of this container.
67
-
79
+
68
80
Fail2ban configuration can seem daunting at first but most of the complexity can be ignored for most users.
69
-
81
+
70
82
In simple terms Fail2ban has three steps with associated configuration files:
71
-
72
-
filters. Think of these as a list of patterns used to match abuse in your log files.
73
-
jails. These are used to tell Fail2ban which log files match which filters and other basics such as how how many failed logins are allowed etc
74
-
actions. As the name suggests these define what actions Fail2ban takes when a jail is triggered. Typical users will never alter these.
75
-
83
+
84
+
`filters` - Think of these as a list of patterns used to match abuse in your log files.
85
+
`jails` - These are used to tell Fail2ban which log files match which filters and other basics such as how how many failed logins are allowed etc
86
+
`actions` - As the name suggests these define what actions Fail2ban takes when a jail is triggered. Typical users will never alter these.
87
+
76
88
Fail2ban continues this one step further with a system that can merge multiple configuration files into one. This is a fairly unusual methodology which can seem confusing at first but is a critical and powerful skill to learn.
77
-
89
+
78
90
This is best explained using an example:
79
-
91
+
80
92
If we ignore actions since almost all users will be happy with the "block IP action" we can concentrate on filters and jails.
81
-
93
+
82
94
Each jail is defined in a .conf file located in /config/fail2ban/jail.d/ so for example nginx-http-auth.conf with contents like:
83
-
95
+
96
+
```ini
84
97
[nginx-http-auth]
85
98
86
99
enabled = false
87
100
filter = nginx-http-auth
88
101
port = http,https
89
102
logpath = /remotelog/nginx/error.log
90
-
103
+
```
104
+
91
105
This file is relatively simple to understand but it is important you do not edit it directly. If you wish to alter this file you have two options:
92
-
106
+
93
107
1. Create a file called nginx-http-auth.local with just the changes you wish to make and the [] header. So for example if you wanted to enable this jail we
94
108
could create a file called nginx-http-auth.local beside the existing nginx-http-auth.conf with contents of
95
-
109
+
110
+
```ini
96
111
[nginx-http-auth]
97
112
98
113
enabled = true
99
-
114
+
```
115
+
100
116
At load tile Fail2ban will read every .conf and .local and merge them internally resulting in this example of turning nginx-http-auth on.
101
-
117
+
102
118
2. Fail2ban also has a jail.conf file that contains global settings but it can also accept jail specific changes.
103
119
As previously you should not edit a conf file so in this case we would create jail.local and enter the same two lines we changed in the previous nginx-http-auth.local example/
104
-
120
+
105
121
Which method is preferable? The choice is yours and both have merits but jail.local is probably easier at first. Should you wish to change later the effort to do so it relatively minimal.
106
-
107
-
At this point you may be asking yourself why all this complication? Once you get used to the setup it soon becomes second nature and it allows lsio and the fail2ban project to push new
108
-
config files and changes such as security fixes without the risk of altering existing user changes.
109
-
122
+
123
+
At this point you may be asking yourself why all this complication? Once you get used to the setup it soon becomes second nature and it allows lsio and the fail2ban project to push new config files and changes such as security fixes without the risk of altering existing user changes.
124
+
110
125
So how do you actually turn on a jail? It is actually relatively simple.
111
-
126
+
112
127
Step 1: In docker volume mount the log file or folder of log files from the container to be protected into this one.
113
128
Step 2: Find the filter that matches the application log type. Most are included by default and more are being added all the time.
114
129
Step 3: Activate the jail using either the global jail.local or jail-specific.local as described above. Normally you only need to change two variables `enabled = true` and the `logpath = /match/your/volume/mount/from/step/1.log`
115
-
130
+
116
131
For neatness we would recommend logs are mount read only using the convention of `/remotelog/containername/nativefilename.log`. So for example our Airsonic container would be:
117
-
118
-
-v <path to containers>/airsonic/airsonic.log:/remotelog/airsonic/airsonic.log:ro
119
132
120
-
Once these three simple steps are taken restart fail2ban and protection should be in place. You can repeat this process to protect any number of containers and given how noisy the internet is in no time you will see
121
-
bad actors being banned.
122
-
133
+
`-v <path to containers>/airsonic/airsonic.log:/remotelog/airsonic/airsonic.log:ro`
134
+
135
+
Once these three simple steps are taken restart fail2ban and protection should be in place. You can repeat this process to protect any number of containers and given how noisy the internet is in no time you will see bad actors being banned.
136
+
123
137
Note: As a safety measure we ship this container with a default ignore list of all IANA private addresses to ensure you do not ban yourself or your LAN users by default. You can alter this using jail.local if you wish.
0 commit comments