Skip to main content

Templates Endpoints

Manage fail2ban jail templates.

List Templates​

Get all available templates.

GET /api/v1/templates

Query Parameters​

ParameterTypeDescription
categorystringFilter by category
typestringbuiltin or custom
searchstringSearch by name or description

Response​

Success (200):

{
  "templates": [
    {
      "id": 1,
      "name": "sshd",
      "display_name": "SSH",
      "description": "Protect SSH from brute-force attacks",
      "category": "common",
      "type": "builtin",
      "default_enabled": true,
      "settings": {
        "maxretry": 5,
        "bantime": 3600,
        "findtime": 600
      }
    },
    {
      "id": 2,
      "name": "nginx-botsearch",
      "display_name": "Nginx Bot Search",
      "description": "Block bots searching for vulnerabilities",
      "category": "web",
      "type": "builtin",
      "default_enabled": false,
      "settings": {
        "maxretry": 2,
        "bantime": 86400,
        "findtime": 86400
      }
    }
  ],
  "total": 24
}

Example​

curl "https://bloqd.example.com/api/v1/templates?category=web" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Template​

Get a specific template by ID or name.

GET /api/v1/templates/{templateId}

Path Parameters​

ParameterTypeDescription
templateIdstringTemplate ID or name

Response​

Success (200):

{
  "id": 1,
  "name": "sshd",
  "display_name": "SSH",
  "description": "Protect SSH from brute-force attacks",
  "category": "common",
  "type": "builtin",
  "default_enabled": true,
  "settings": {
    "maxretry": 5,
    "bantime": 3600,
    "findtime": 600,
    "logpath": "/var/log/auth.log"
  },
  "jail_config": "[sshd]\nenabled = true\nport = ssh\nfilter = sshd\nlogpath = %(sshd_log)s\nmaxretry = 5\nbantime = 3600\nfindtime = 600",
  "filter_config": "[Definition]\nfailregex = ^%(__prefix_line)s(?:error: PAM: )?...",
  "required_files": ["/var/log/auth.log"],
  "compatible_os": ["ubuntu", "debian", "centos", "rhel"]
}

Create Custom Template​

Create a new custom template.

POST /api/v1/templates

Request Body​

{
  "name": "my-custom-app",
  "display_name": "My Custom App",
  "description": "Protect my custom application",
  "category": "custom",
  "settings": {
    "maxretry": 3,
    "bantime": 7200,
    "findtime": 300,
    "logpath": "/var/log/myapp/auth.log"
  },
  "jail_config": "[my-custom-app]\nenabled = true\nport = 8080\nfilter = my-custom-app\nlogpath = /var/log/myapp/auth.log\nmaxretry = 3\nbantime = 7200\nfindtime = 300",
  "filter_config": "[Definition]\nfailregex = ^.*Failed login attempt from <HOST>.*$\nignoreregex ="
}

Response​

Success (201):

{
  "id": 25,
  "name": "my-custom-app",
  "display_name": "My Custom App",
  "type": "custom",
  "created_at": "2024-01-15T10:30:00Z"
}

Update Template​

Update a custom template.

PATCH /api/v1/templates/{templateId}

Path Parameters​

ParameterTypeDescription
templateIdintegerTemplate ID

Request Body​

{
  "display_name": "My Custom App v2",
  "settings": {
    "maxretry": 5,
    "bantime": 3600
  }
}

Response​

Success (200):

{
  "id": 25,
  "name": "my-custom-app",
  "display_name": "My Custom App v2",
  "updated_at": "2024-01-15T10:30:00Z"
}
warning

Built-in templates cannot be modified.

Delete Template​

Delete a custom template.

DELETE /api/v1/templates/{templateId}

Path Parameters​

ParameterTypeDescription
templateIdintegerTemplate ID

Response​

Success (200):

{
  "message": "Template deleted"
}
warning

Built-in templates cannot be deleted.

Deploy Template​

Deploy a template to one or more servers.

POST /api/v1/templates/{templateId}/deploy

Path Parameters​

ParameterTypeDescription
templateIdintegerTemplate ID

Request Body​

{
  "server_ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001"
  ],
  "settings": {
    "maxretry": 3,
    "bantime": 7200
  }
}

Response​

Success (200):

{
  "message": "Deployment queued",
  "commands": [
    {
      "server_id": "550e8400-e29b-41d4-a716-446655440000",
      "command_id": "cmd-abc123"
    },
    {
      "server_id": "550e8400-e29b-41d4-a716-446655440001",
      "command_id": "cmd-abc124"
    }
  ]
}

Remove Template from Server​

Remove a deployed template from a server.

DELETE /api/v1/templates/{templateId}/servers/{serverId}

Path Parameters​

ParameterTypeDescription
templateIdintegerTemplate ID
serverIdstringServer UUID

Response​

Success (200):

{
  "message": "Removal queued",
  "command_id": "cmd-abc125"
}

Get Template Categories​

Get all template categories.

GET /api/v1/templates/categories

Response​

Success (200):

{
  "categories": [
    {
      "id": "common",
      "name": "Common",
      "description": "Essential protection templates",
      "template_count": 2
    },
    {
      "id": "web",
      "name": "Web Servers",
      "description": "Nginx, Apache, and web application templates",
      "template_count": 6
    },
    {
      "id": "mail",
      "name": "Mail Servers",
      "description": "Postfix, Dovecot, and mail templates",
      "template_count": 4
    },
    {
      "id": "custom",
      "name": "Custom",
      "description": "User-created templates",
      "template_count": 1
    }
  ]
}

Validate Template​

Validate template configuration without deploying.

POST /api/v1/templates/validate

Request Body​

{
  "jail_config": "[my-jail]\nenabled = true\nport = 8080",
  "filter_config": "[Definition]\nfailregex = ^.*$"
}

Response​

Success (200):

{
  "valid": true,
  "warnings": [
    "Filter regex is very broad and may cause false positives"
  ]
}

Invalid:

{
  "valid": false,
  "errors": [
    "Missing required 'filter' directive in jail config",
    "Invalid regex syntax in filter_config"
  ]
}

Get Deployment Status​

Check template deployment status on servers.

GET /api/v1/templates/{templateId}/status

Response​

Success (200):

{
  "template_id": 1,
  "template_name": "sshd",
  "servers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "hostname": "web-server-01",
      "deployed": true,
      "enabled": true,
      "current_bans": 3
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "hostname": "web-server-02",
      "deployed": true,
      "enabled": false,
      "current_bans": 0
    }
  ]
}