BanGUI/Docs/Tasks.md

BanGUI — Task List

This document breaks the entire BanGUI project into development stages, ordered so that each stage builds on the previous one. Every task is described in prose with enough detail for a developer to begin work. References point to the relevant documentation.

---

✅ Task 1 — Convert Backend, Log Encoding, and Date Pattern to Dropdowns in Jail Config

Completed. Backend and Log Encoding are now <Select> dropdowns; Date Pattern is a <Combobox> with presets. Both are wired to auto-save. The JailConfigDetail component also gained a readOnly prop (wired throughout all fields, toggles, and buttons) in preparation for Task 3. Backend updated JailConfigUpdate model to accept backend and log_encoding, and update_jail_config sends them to the daemon.

---

✅ Task 2 — Fix Raw Action Configuration Always Blank in Actions Tab

Completed. Added key={selectedAction.name} to <ActionDetail> in ActionsTab.tsx and key={selectedFilter.name} to <FilterDetail> in FiltersTab.tsx. This forces a full remount on item switch, resetting RawConfigSection's loadedRef so it re-fetches content for every selected item.

---

✅ Task 3 — Give Inactive Jail Configs the Same GUI as Active Ones

Completed. Extended InactiveJail backend Pydantic model with all config fields (ban_time_seconds, find_time_seconds, log_encoding, backend, date_pattern, use_dns, prefregex, fail_regex, ignore_regex, bantime_escalation). Added _parse_time_to_seconds helper to config_file_service.py and updated _build_inactive_jail to populate all new fields. Extended the InactiveJail TypeScript type to match. Rewrote InactiveJailDetail to map fields into a JailConfig-compatible object and render JailConfigDetail with readOnly=true, showing filter/port/source_file as informational fields above the shared form.

---

✅ Task 4 — Fix banaction Interpolation Error When Activating Jails

Completed. _write_local_override_sync now always writes banaction = iptables-multiport and banaction_allports = iptables-allports into the per-jail .local file (Option A), ensuring fail2ban can resolve the %(banaction)s interpolation used in action_.

Problem: In the Config → Jails page, the Backend, Log Encoding, and Date Pattern fields for active jails are currently plain text <Input> fields (Backend and Log Encoding are read-only, Date Pattern is a free-text input). These should be <Select> dropdowns so users pick from valid options instead of typing arbitrary values.

Where to change:

• frontend/src/components/config/JailsTab.tsx — the JailConfigDetail component, around lines 250–270. This is the right-pane form for active jails. Replace the three <Input> fields with <Select> dropdowns.

Dropdown options to use:

Backend

Reference: fail2ban-master/config/jail.conf lines 115–132. The JailFileForm.tsx already defines a BACKENDS constant at line 163 — reuse or mirror it.

Value	Label
auto	auto — pyinotify, then polling
polling	polling — standard polling algorithm
pyinotify	pyinotify — requires pyinotify library
systemd	systemd — uses systemd journal
gamin	gamin — legacy file alteration monitor

Log Encoding

Reference: fail2ban-master/config/jail.conf lines 145–150. The option auto uses the system locale; the rest are standard Python codec names.

Value	Label
auto	auto — use system locale
ascii	ascii
utf-8	utf-8
latin-1	latin-1 (ISO 8859-1)

Date Pattern

Date Pattern should remain a combobox (editable dropdown) since users may enter custom patterns, but offer common presets as suggestions.

Value	Label
(empty)	auto-detect (leave blank)
{^LN-BEG}	{^LN-BEG} — line beginning
%%Y-%%m-%%d %%H:%%M:%%S	YYYY-MM-DD HH:MM:SS
%%d/%%b/%%Y:%%H:%%M:%%S	DD/Mon/YYYY:HH:MM:SS (Apache)
%%b %%d %%H:%%M:%%S	Mon DD HH:MM:SS (syslog)
EPOCH	EPOCH — Unix timestamp
%%Y-%%m-%%dT%%H:%%M:%%S	ISO 8601
TAI64N	TAI64N

Implementation notes:

1. Backend and Log Encoding are currently readOnly. They must become editable <Select> fields. Wire their onChange to local state and include them in the auto-save payload sent to the backend.
2. The backend model at backend/app/models/config.py line 67 already accepts backend: str and log_encoding: str, so no backend changes are needed unless you want to add server-side validation.
3. Date Pattern should use a Fluent UI Combobox (editable dropdown) instead of a Select, so users can still type a custom pattern.
4. Follow the existing DNS Mode dropdown pattern at lines 271–280 of JailsTab.tsx as a reference for styling and onChange handling.

---

Task 2 — Fix Raw Action Configuration Always Blank in Actions Tab

Problem: In the Config → Actions page, the "Raw Action Configuration" accordion section is always blank when expanded.

Where to look:

• frontend/src/components/config/ActionsTab.tsx — the ActionDetail component (lines 65–185). The fetchRaw callback (line 82) calls fetchActionFile(action.name) and returns result.content.
• frontend/src/components/config/RawConfigSection.tsx — the collapsible raw editor. It uses a loadedRef (line 62) to fetch content only on first accordion expansion, and never resets.
• frontend/src/api/config.ts line 257 — fetchActionFile() calls GET /config/actions/{name}.
• backend/app/services/file_config_service.py line 734 — get_action_file() reads from action.d/ using _read_conf_file(), which tries .conf first, then .local.

Root cause investigation — check these two possibilities:

Possibility A: Stale loadedRef across action switches

ActionDetail at line 301 of ActionsTab.tsx is rendered without a key prop:

<ActionDetail
  action={selectedAction}
  onAssignClick={() => { setAssignOpen(true); }}
  onRemovedFromJail={handleRemovedFromJail}
/>

Without key={selectedAction.name}, React reuses the same component instance when switching between actions. The RawConfigSection inside ActionDetail keeps its loadedRef.current = true from a previous expansion, so it never re-fetches for the new action.

Fix: Add key={selectedAction.name} to ActionDetail so it fully unmounts/remounts on action switch, resetting all internal state including loadedRef.

Possibility B: Backend returning empty content

The _read_conf_file function at file_config_service.py line 492 tries .conf first then .local. If the action only has a .conf file and it's readable, content should be returned. Verify by:

1. Checking browser DevTools Network tab for the GET /api/config/actions/{name} response body.
2. Confirming the response has a non-empty content field.

Implementation:

1. Add key={selectedAction.name} to the <ActionDetail> component in ActionsTab.tsx line 301.
2. Test by selecting different actions and expanding the raw config accordion — each should show the correct file content.
3. If the backend is returning empty content, debug _read_conf_file to check which file path it resolves and whether it can read the file.

---

Task 3 — Give Inactive Jail Configs the Same GUI as Active Ones

Problem: In the Config → Jails page, inactive jails show a minimal read-only preview (InactiveJailDetail component) with only basic fields (filter, port, ban time, find time, max retry, log paths, actions, source file). Active jails like bangui-sim show a full editable form (JailConfigDetail component) with all fields including Backend, Log Encoding, Date Pattern, DNS Mode, Prefix Regex, editable log paths, Fail/Ignore Regex lists, Ban-time Escalation, and a Raw Configuration editor.

The inactive jail detail should display the same rich GUI as the active one — same layout, same fields — but in read-only mode (since the jail is not running on fail2ban).

Where to change:

• frontend/src/components/config/JailsTab.tsx:

  • InactiveJailDetail component (lines 493–580): the current minimal read-only view.
  • JailConfigDetail component (lines ~200–490): the full editable form for active jails.
  • Selection logic at lines 721–752 determines which component renders based on jail kind.

• frontend/src/types/config.ts — InactiveJail type (around line 484) defines the data shape for inactive jails. Compare with JailConfig to see which fields are missing.

• Backend — check that the inactive jail endpoint returns enough data. The backend model InactiveJail may need additional fields (backend, log_encoding, date_pattern, dns_mode, prefix_regex, failregex, ignoreregex, ban-time escalation settings) to match the active JailConfig model.

Implementation approach:

1. Extend the InactiveJail model in the backend (backend/app/models/config.py) to include all fields that JailConfig has: backend, log_encoding, date_pattern, usedns, prefixregex, failregex, ignoreregex, bantime_increment (escalation settings), etc.
2. Update the backend service that parses inactive jail configs to extract these additional fields from the .conf/.local files.
3. Rewrite InactiveJailDetail to mirror JailConfigDetail's layout but with all fields in read-only mode (all <Input> have readOnly, all <Select> are disabled). Keep the "Activate Jail" button at the bottom.
4. Alternatively, refactor JailConfigDetail to accept a readOnly prop and reuse it for both active and inactive jails, avoiding code duplication.
5. Include the Raw Configuration accordion (using RawConfigSection) for inactive jails as well, pointed at the jail's config file.

Testing: Select an inactive jail and verify it shows the same fields and layout as an active jail like bangui-sim, with all values populated from the config file but not editable.

---

Task 4 — Fix banaction Interpolation Error When Activating Jails

Problem: Activating certain jails (e.g. airsonic-auth) causes fail2ban to crash with:

ERROR  Failed during configuration: Bad value substitution: option 'action'
in section 'airsonic-auth' contains an interpolation key 'banaction' which
is not a valid option name. Raw value: '%(action_)s'

Root cause — the interpolation chain breaks:

1. Most jails inherit action = %(action_)s from [DEFAULT].
2. action_ is defined in fail2ban-master/config/jail.conf line 212 as:

   action_ = %(banaction)s[port="%(port)s", protocol="%(protocol)s", chain="%(chain)s"]
   

3. banaction is commented out in the [DEFAULT] section of jail.conf (line 208):

   #banaction = iptables-multiport
   #banaction_allports = iptables-allports
   

4. When BanGUI activates a jail, _write_local_override_sync() in backend/app/services/config_file_service.py (line 478) writes a .local file with only enabled, bantime, findtime, maxretry, port, and logpath — it does not include banaction or action.
5. fail2ban merges the configs, hits %(banaction)s, finds no value, and crashes.

Where to change:

• backend/app/services/config_file_service.py — function _write_local_override_sync() around line 478. This writes the per-jail .local override file.
• backend/app/models/config.py — the ActivateJailRequest or equivalent model that defines which fields are accepted when activating a jail.

Fix options (pick one):

Option A: Write banaction in every jail .local file (recommended)

When BanGUI writes a jail .local file, include a banaction field with a sensible default (e.g. iptables-multiport). This ensures the interpolation chain always resolves.

1. Add a banaction field (defaulting to iptables-multiport) to the jail activation model/request.
2. In _write_local_override_sync(), always write banaction = <value> into the [jailname] section of the .local file.
3. Also include banaction_allports = iptables-allports as a fallback for jails that reference it.

Option B: Write a global jail.local with DEFAULT banaction

Create or update a jail.local file in the fail2ban config directory with:

[DEFAULT]
banaction = iptables-multiport
banaction_allports = iptables-allports

This provides the missing defaults for all jails at once.

Option C: Expose banaction in the jail config UI

Add banaction as a configurable field in the jail config form so users can choose the ban action (iptables-multiport, nftables-multiport, firewallcmd-rich-rules, etc.). Write the selected value to the .local file on save/activate.

Testing:

1. Activate airsonic-auth (or any jail that inherits action = %(action_)s without defining its own banaction).
2. Verify fail2ban starts without the interpolation error.
3. Verify fail2ban-client status airsonic-auth shows the jail running with the correct ban action.