|
| 1 | +--- |
| 2 | + |
| 3 | +# project information |
| 4 | +project_name: fail2ban |
| 5 | +project_url: "https://github.com/fail2ban/fail2ban" |
| 6 | +project_logo: "https://raw.githubusercontent.com/linuxserver/docker-templates/master/linuxserver.io/img/fail2ban-banner.png" |
| 7 | +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." |
| 8 | + |
| 9 | + |
| 10 | +project_lsio_github_repo_url: "https://github.com/linuxserver/docker-{{ project_name }}" |
| 11 | +project_blurb_optional_extras_enabled: false |
| 12 | + |
| 13 | +# supported architectures |
| 14 | +available_architectures: |
| 15 | + - { arch: "{{ arch_x86_64 }}", tag: "amd64-latest"} |
| 16 | + - { arch: "{{ arch_arm64 }}", tag: "arm64v8-latest"} |
| 17 | + - { arch: "{{ arch_armhf }}", tag: "arm32v7-latest"} |
| 18 | + |
| 19 | +# development version |
| 20 | +development_versions: true |
| 21 | +development_versions_items: |
| 22 | + - { tag: "latest", desc: "Stable Fail2ban Releases" } |
| 23 | + - { tag: "development", desc: "Latest Fail2ban Releases" } |
| 24 | + |
| 25 | +# container parameters |
| 26 | +common_param_env_vars_enabled: true |
| 27 | +param_container_name: "{{ project_name }}" |
| 28 | +param_usage_include_net: false |
| 29 | +param_usage_include_env: true |
| 30 | +param_env_vars: |
| 31 | + - { env_var: "TZ", env_value: "Europe/London", desc: "Specify a timezone to use EG Europe/London." } |
| 32 | +param_usage_include_vols: true |
| 33 | +param_volumes: |
| 34 | + - { vol_path: "/config", vol_host_path: "<path to data>", desc: "Where Fail2ban should store its config file." } |
| 35 | + - { vol_path: "/remotelog/applicationX/applicationX.log", vol_host_path: "<path to applicationX.log>", desc: "Path to a specific named log file." } |
| 36 | + - { vol_path: "/remotelog/applicationY/", vol_host_path: "<path to applicationY log directory>", desc: "Path to an application log directory with multiple logs." } |
| 37 | +param_usage_include_ports: false |
| 38 | +param_ports: |
| 39 | +param_device_map: false |
| 40 | +cap_add_param: false |
| 41 | + |
| 42 | +# optional container parameters |
| 43 | +opt_param_usage_include_env: false |
| 44 | +opt_param_env_vars: |
| 45 | +opt_param_usage_include_vols: false |
| 46 | +opt_param_usage_include_ports: false |
| 47 | +opt_param_device_map: false |
| 48 | +opt_cap_add_param: true |
| 49 | +optional_block_1: false |
| 50 | + |
| 51 | +# application setup block |
| 52 | +app_setup_block_enabled: true |
| 53 | +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 | + |
| 57 | + To do this it takes advantage of the DOCKER-USER iptables chain that exists in all modern docker installs. |
| 58 | + |
| 59 | + 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 | + |
| 61 | + 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 | + |
| 66 | + 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 | + |
| 68 | + Fail2ban configuration can seem daunting at first but most of the complexity can be ignored for most users. |
| 69 | + |
| 70 | + 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 | + |
| 76 | + 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 | + |
| 78 | + This is best explained using an example: |
| 79 | + |
| 80 | + If we ignore actions since almost all users will be happy with the "block IP action" we can concentrate on filters and jails. |
| 81 | + |
| 82 | + 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 | + |
| 84 | + [nginx-http-auth] |
| 85 | +
|
| 86 | + enabled = false |
| 87 | + filter = nginx-http-auth |
| 88 | + port = http,https |
| 89 | + logpath = /remotelog/nginx/error.log |
| 90 | + |
| 91 | + 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 | + |
| 93 | + 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 | + could create a file called nginx-http-auth.local beside the existing nginx-http-auth.conf with contents of |
| 95 | + |
| 96 | + [nginx-http-auth] |
| 97 | +
|
| 98 | + enabled = true |
| 99 | + |
| 100 | + 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 | + |
| 102 | + 2. Fail2ban also has a jail.conf file that contains global settings but it can also accept jail specific changes. |
| 103 | + 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 | + |
| 105 | + 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 | + |
| 110 | + So how do you actually turn on a jail? It is actually relatively simple. |
| 111 | + |
| 112 | + Step 1: In docker volume mount the log file or folder of log files from the container to be protected into this one. |
| 113 | + 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 | + 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 | + |
| 116 | + 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 | +
|
| 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 | + |
| 123 | + 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. |
| 124 | + |
| 125 | +
|
| 126 | +# changelog |
| 127 | + |
| 128 | +changelogs: |
| 129 | + - { date: "xx.xx.20:", desc: "Initial Release." } |
| 130 | + |
0 commit comments