Runtime management of per-jail exclusions

[ul0gic]

This proposal would add commands to manage persistent per-jail exclusions alongside the existing configuration-based ignoreip lists.

Before deciding whether to implement it, we need to establish:

• User workflows that benefit from runtime management.
• How configuration and runtime entries combine and are displayed.
• Whether exclusions are permanent or can expire.
• How additions and removals affect existing bans.

Concrete use cases and proposed behavior are welcome. This is exploratory design work, with no implementation or release commitment.

Origin: #102. The existing configuration-update limitation is tracked separately.

[ul0gic]

@mwriter Runtime exclusion management could provide value for automation and temporary operational exceptions without requiring configuration-file edits. Optional expiration could also prevent temporary exceptions from becoming permanent unintentionally.

There is precedent: Fail2ban supports runtime per-jail ignore-list changes, while CrowdSec provides persistent database-managed allowlists with optional expiration. Their persistence and existing-ban behavior differ.

For fail2zig, a starting point would be per-jail add, remove and list operations, with output distinguishing configuration entries from runtime entries. Configuration-defined exclusions should remain controlled by configuration.

The main behavior to resolve is whether adding an exclusion only prevents future bans or also removes an existing ban. Expiration and removal semantics also need to be explicit. Command naming can follow those decisions.

One concern is making the effective policy clear when configuration and runtime entries overlap. Removing a runtime entry must not imply that an address is subject to bans again if configuration still excludes it. Likewise, any removal of existing bans must be explicit and limited to the selected jail.

[mwriter]

The main behavior to resolve is whether adding an exclusion only prevents future bans or also removes an existing ban.

It should definitely be removed from the ban. But you can also make an additional flag --force.

Expiration and removal semantics also need to be explicit.

I wasn't hoping for that yet :D But additional time options would be a great addition.

[mwriter]

• User workflows that benefit from runtime management

If there are a lot of ignore addresses, it's more convenient to manage them in a non-text configuration.
Especially if we want to do it quickly in runtime with one command.

[mwriter]

• How configuration and runtime entries combine and are displayed.

Let's make it a simple merge to simplify.

[mwriter]

• Whether exclusions are permanent or can expire

Yep, then we will need to add two commands: fail2zig ignore and fail2zig notice.

[mwriter]

• How additions and removals affect existing bans.

Adding an address to the ignored list should, of course, exclude it from banned for the corresponding jail. But you can also make an additional flag --force.
And now the setting ignoreip is allowed only at the jail level or globally too?

[ul0gic]

@mwriter Those are definitely useful cases to design around, especially when managing a larger list or making changes through automation.

To answer your question, ignoreip works in both [defaults] and individual jails. A jail inherits the defaults unless it supplies its own list, which replaces them.

I think merging runtime entries with the jail’s effective configuration list makes sense. We should still show where each entry comes from, though, so it’s clear why an address is excluded. Something like:

$ fail2zig ignore list --jail sshd

ADDRESS          SOURCE     EXPIRES
192.0.2.10       config     never
198.51.100.20    runtime    never
203.0.113.30     runtime    28m

What about ignore add, ignore remove and ignore list for the commands? They keep everything together, and remove says more directly what happens than notice.

I also see why you’d want to exclude an address and lift its ban in one command. My preference would be --unban rather than --force, since it tells you exactly what you’re asking for:

fail2zig ignore add 198.51.100.20 --jail sshd --unban

Without that option, an existing ban would run its course, but future automatic bans would be prevented. With it, we’d also remove the selected jail’s ban.

The overlap is the part we need to get right: removing a runtime entry won’t stop an address being excluded if configuration still covers it. The command should tell you that directly. Otherwise, removal would simply make the address eligible for normal detection again.

Expiration would be useful too, but we can settle the basic add/remove behavior first.

[mwriter]

What about ignore add, ignore remove and ignore list for the commands?

Yep, this idea is better.

[ul0gic]

Shipped in v0.4.7: fail2zig ignore add <address|cidr> --jail <name> [--unban], ignore remove, and ignore list [--jail <name>]. Runtime entries survive restart and reload and merge with the configured ignoreip; an existing ban stays until its deadline unless --unban is given, and the output names the exact command that lifts it. ignore list shows whether each entry comes from the configuration, the runtime, or both. Literal ignoreip edits also apply through reload now without a restart refusal. The manual page has the details.

[mwriter]

@ul0gic

I came up with a new idea.
Or maybe add a similar setting as banip to the configuration file, but to block some addresses immediately?
In that case, it makes sense to add the same commands to separate the source of the banned addresses.

[ul0gic]

@mwriter That makes sense. Here's what we could do: keep a single banip list, where each entry is permanent by default and can optionally carry its own duration:

banip = [
  "203.0.113.5",              # banned for as long as it stays in the list
  "198.51.100.0/24 for 1d",   # banned for one day, then it expires
]

That gives you both categories in one place, with a different duration per entry rather than only the jail's bantime. Every ban would still show where it came from (config), and timed entries would show the time remaining.

What do you think? Would this work for how you'd use it, or would you rather have the two kinds as separate lists?

[mwriter]

What do you think? Would this work for how you'd use it, or would you rather have the two kinds as separate lists?

I like that idea.
Maybe even remove for?

banip = [
  "203.0.113.5", 
  "198.51.100.0/24 1d",
]

[mwriter]

# banned for one day, then it expires

By the way, is there already something like that for ignoreip?
To specify the ignore period directly in the configuration file.

[ul0gic]

@mwriter Agreed on both counts.

Dropping for works: an address never contains a space, so "198.51.100.0/24 1d" reads cleanly. Anything after the address that isn't a valid duration will be a config error naming the entry, so a typo like 1dd can't quietly turn into a permanent ban.

And yes, ignoreip will get the same syntax, so you can trust an address for a set period right in the config:

ignoreip = [
  "10.0.0.0/8",
  "198.51.100.7 7d",
]

The one rule both lists share: a period starts when the entry is first applied and runs out once. A reload or restart won't restart the clock (otherwise 1d would quietly last forever on a box that reloads daily). Changing the duration, or removing and re-adding the entry, starts a fresh period. An entry that has run out stays in the file but does nothing, and ignore list / list show it as expired so it's easy to clean up.

Does that match what you had in mind?

[mwriter]

Does that match what you had in mind?

It looks great :D

[mwriter]

@ul0gic

By the way, one more question.
Shouldn't we add a setting ignoretime?

[ul0gic]

@mwriter Yes, and part of it is already in the 0.4.8 plan. An ignore entry gets an optional duration: ignore add 203.0.113.9 --jail sshd --for 2m at runtime, or ignoreip = ["203.0.113.9 1d"] in the config. ignore list shows the time left, the entry survives a restart with its deadline, and when it lapses only the exclusion goes away, nothing else.

An ignoretime setting on top of that makes sense as the default for entries that don't carry their own duration: global, overridable per jail, and an explicit duration on the entry wins. The one thing I'd keep is the default of "never expires" when ignoretime isn't set. Most ignoreip lists are meant to be permanent (that's how fail2ban's behaves too), and having them quietly lapse would surprise people.

So: ignoretime unset means permanent, set means that's the default life of an exclusion, and --for or a duration on the entry overrides it either way. Does that match what you had in mind? I'll add it to the 0.4.8 scope on that basis.

[mwriter]

Does that match what you had in mind?

Yep :D

[ul0gic]

Shipped in v0.4.8:

• banip, in [defaults] and per jail: addresses and CIDRs banned while listed, lifted when removed and the config is reloaded. Each entry is permanent or timed: "198.51.100.0/24 1d".
• Every ban shows its origin, detection, manual or config, in list (--origin filters), history and firewall show.
• ignoreip entries take the same optional duration ("198.51.100.7 7d"); the period starts when the entry is first applied and runs once, a reload or restart never restarts it, and an expired entry stays in the file and shows as expired.
• ignore add ... --for <duration> for runtime entries, and ignoretime (global, per-jail override, unset or 0 means permanent) as the default life of an entry without its own duration.

The manual page documents each one. @mwriter, this thread was the spec; thank you.