Skip to main content

Custom Templates

Create your own templates for custom applications. (Personal+ license required)

Creating a Custom Template​

Via Dashboard​

  1. Go to Templates page
  2. Click Create Template
  3. Fill in template details:
    • Name: Unique identifier (lowercase, hyphens)
    • Display Name: Friendly name shown in UI
    • Category: For organization
    • Description: What the template protects
  4. Define the filter regex
  5. Define the jail configuration
  6. Save template

Copy Existing Template​

Start from a builtin template:

  1. Find a similar builtin template
  2. Click Copy action
  3. Modify filter/jail as needed
  4. Save with new name

Filter Definition​

Basic Structure​

[Definition]
failregex = ^.*authentication failed from <HOST>.*$
ignoreregex =

Key Elements​

ElementDescription
<HOST>IP extraction placeholder (required)
^Start of line
$End of line
.*Match any characters
\sWhitespace
\d+One or more digits
\[ \]Literal brackets (escaped)

Multiple Patterns​

failregex = ^.*pattern one from <HOST>.*$
            ^.*pattern two from <HOST>.*$
            ^.*pattern three from <HOST>.*$

Each pattern on its own line, indented.

Ignore Patterns​

Exclude certain lines from matching:

ignoreregex = ^.*successful login.*$
              ^.*health check.*$

Date Pattern​

Help fail2ban parse log timestamps:

datepattern = ^%%Y-%%m-%%d %%H:%%M:%%S

Common formats:

FormatExample
%%Y-%%m-%%d %%H:%%M:%%S2024-01-15 10:30:00
%%b %%d %%H:%%M:%%SJan 15 10:30:00
%%d/%%b/%%Y:%%H:%%M:%%S %%z15/Jan/2024:10:30:00 +0000
{^LN-BEG}Auto-detect (use for nginx error logs)

Jail Configuration​

Basic Structure​

[my-app]
enabled = true
port = 8080
filter = my-app
logpath = /var/log/my-app/access.log
maxretry = 5
findtime = 10m
bantime = 1h

Using Placeholders​

Use placeholders for user-configurable values:

[my-app]
enabled = true
port = __PORT__
filter = my-app
logpath = __LOGPATH__
maxretry = __MAXRETRY__
findtime = __FINDTIME__
bantime = __BANTIME__
PlaceholderDescription
__LOGPATH__Log file path
__PORT__Service port
__MAXRETRY__Max retry count
__FINDTIME__Find time window
__BANTIME__Ban duration

Placeholders are replaced with actual values during deployment.

Multiple Ports​

port = 8080,8443
# or
port = http,https

Backend Options​

BackendUse Case
autoAuto-detect (default)
pollingDocker logs, slow-updating logs
systemdSystemd journal
pyinotifyFile system notifications

Docker Templates​

For containerized applications:

Template Settings​

is_docker: true
docker_container_filter: "name=my-container"

Log Streaming​

Bloqd creates a systemd service to stream logs:

[Service]
ExecStart=/usr/bin/docker logs -f my-container
StandardOutput=append:/var/log/bloqd/my-container.log

Jail Configuration​

[my-docker-app]
enabled = true
port = 8080
filter = my-docker-app
logpath = /var/log/bloqd/my-container.log
backend = polling

Always use backend = polling for Docker logs.

Testing Custom Templates​

Test Filter Regex​

# Against a log file
fail2ban-regex /var/log/my-app.log /etc/fail2ban/filter.d/my-app.conf

# Against sample lines
fail2ban-regex "2024-01-15 Auth failed from 192.168.1.100" \
  /etc/fail2ban/filter.d/my-app.conf

Preview in Dashboard​

  1. Click Preview on template
  2. Enter sample values
  3. View generated filter.conf and jail.conf

Test on Server​

  1. Deploy template to a test server
  2. Check jail status: 
    fail2ban-client status my-app
  3. Generate test failures
  4. Verify ban occurs

Best Practices​

Filter Design​

  1. Be specific: Match only the failure pattern
  2. Test thoroughly: Use real log samples
  3. Handle variations: Different log formats across versions
  4. Use datepattern: Help fail2ban parse timestamps

Naming​

  • Use lowercase with hyphens: my-custom-app
  • Include service name: myapp-auth
  • Be descriptive: wordpress-xmlrpc

Documentation​

Add clear description:

  • What the template protects
  • What log format it expects
  • Any special requirements

Maintenance​

  • Test after application updates
  • Update regex if log format changes
  • Document changes

Example: Custom Application​

Application Log Format​

2024-01-15 10:30:00 [ERROR] Authentication failed for user 'admin' from IP 192.168.1.100

Filter​

[Definition]
failregex = ^.*\[ERROR\] Authentication failed for user '.*' from IP <HOST>.*$
ignoreregex =
datepattern = ^%%Y-%%m-%%d %%H:%%M:%%S

Jail​

[my-app]
enabled = true
port = 8080
filter = my-app
logpath = __LOGPATH__
maxretry = __MAXRETRY__
findtime = __FINDTIME__
bantime = __BANTIME__

Default Values​

  • Log Path: /var/log/my-app/app.log
  • Port: 8080
  • Max Retry: 5
  • Find Time: 10m
  • Ban Time: 1h