Update README.md

roles/fail2ban_rhel/README.md

@@ -1,49 +1,78 @@
-fail2ban_rhel
+# fail2ban_rhel
-=============
 
-A small role to deploy `fail2ban` on RHEL/Rocky 9+ hosts. Currently supports only a templated `sshd` jail.
+A small role to deploy a lean `fail2ban` configuration on RHEL/Rocky 9+ hosts.
+Currently supports a templated `sshd` jail.
 
-Requirements
+## Requirements
-------------
 
 - Target hosts must be RHEL-family or Rocky Linux 9+
 
-Supported Platforms
+## Supported Platforms
--------------------
 
 - RHEL 9+
 - Rocky Linux 9+
 
-Role Variables
+## Defaults
---------------
 
-sshd jail configuration
+The role exposes flat defaults for the `sshd` jail. These values are assembled
+into the internal `fail2ban_rhel_jail_sshd` mapping in `vars/main.yml` and then
+rendered into `/etc/fail2ban/jail.d/sshd.local`.
 
-- `fail2ban_rhel_jail_sshd`:
+| Variable | Default | Description |
-    `enabled`: enable the sshd jail. Default: `true`
+| --- | --- | --- |
-    `port`: fail2ban port for sshd. Default: `ssh`
+| `fail2ban_rhel_jail_sshd_enabled` | `true` | Enable the `sshd` jail. |
-    `logpath`: path to the SSH log file. Default: `/var/log/secure`
+| `fail2ban_rhel_jail_sshd_port` | `ssh` | Port or service name watched by the jail. |
-    `findtime`: time window for fail2ban. Default: `600`
+| `fail2ban_rhel_jail_sshd_findtime` | `600` | Time window, in seconds, used when counting failures. |
-    `maxretry`: maximum retry count. Default: `5`
+| `fail2ban_rhel_jail_sshd_maxretry` | `5` | Number of failures allowed within `findtime`. |
-    `bantime`: ban duration in seconds. Default: `600`
+| `fail2ban_rhel_jail_sshd_bantime` | `3600` | Ban duration, in seconds. |
-    `ignoreips`: list of IPs and CIDRs that fail2ban should ignore. Default: `127.0.0.1/8`, `::1`
+| `fail2ban_rhel_jail_sshd_logpath` | `%(sshd_log)s` | Fail2Ban's platform default SSH log path token. |
+| `fail2ban_rhel_jail_sshd_backend` | `%(sshd_backend)s` | Fail2Ban's platform default SSH backend token. |
+| `fail2ban_rhel_jail_sshd_banaction` | `firewallcmd-multiport` | Ban action used by the jail. |
+| `fail2ban_rhel_jail_sshd_ignoreips` | `127.0.0.1/8`, `::1` | IPs and CIDRs that should never be banned. |
 
-Behavior
+## Internal Vars
---------
+
+`vars/main.yml` builds the `fail2ban_rhel_jail_sshd` dictionary consumed by the
+`sshd.conf.j2` template:
+
+```yaml
+fail2ban_rhel_jail_sshd:
+  enabled: "{{ fail2ban_rhel_jail_sshd_enabled }}"
+  port: "{{ fail2ban_rhel_jail_sshd_port }}"
+  findtime: "{{ fail2ban_rhel_jail_sshd_findtime }}"
+  maxretry: "{{ fail2ban_rhel_jail_sshd_maxretry }}"
+  bantime: "{{ fail2ban_rhel_jail_sshd_bantime }}"
+  logpath: "{{ fail2ban_rhel_jail_sshd_logpath }}"
+  backend: "{{ fail2ban_rhel_jail_sshd_backend }}"
+  banaction: "{{ fail2ban_rhel_jail_sshd_banaction }}"
+  ignoreips: "{{ fail2ban_rhel_jail_sshd_ignoreips }}"
+```
+
+Override the flat defaults, not the internal mapping, unless you intentionally
+want to replace the rendered jail data.
+
+## Behavior
 
 By default this role:
 
-- installs `epel-release` on RedHat-family systems when enabled
+- installs `epel-release`
 - installs `fail2ban`
-- creates `/etc/fail2ban/jail.d/sshd.conf` from a template
+- renders `/etc/fail2ban/jail.d/sshd.local` from `templates/sshd.conf.j2`
-- enables and starts the `fail2ban` systemd service
+- restarts and enables `fail2ban` when the rendered jail changes
 
-Example Playbook
+## Example Playbook
-----------------
 
-See: `molecule/default/converge.yml`
+```yaml
+- name: Converge
+  hosts: all
+  roles:
+    - role: genlab.common.fail2ban_rhel
+      fail2ban_rhel_jail_sshd_maxretry: 4
+      fail2ban_rhel_jail_sshd_bantime: 7200
+```
 
-License
+See also: `molecule/default/converge.yml`
--------
+
+## License
 
 MIT