# Fail2Ban

<a id="post-api-v1-fail2ban-ban"></a>
#### `POST /api/v1/fail2ban/ban`

*Manually ban an IP*

Adds an IP (or, in an HTTP-facing jail, a network) to the specified jail's banned set immediately. A whitelisted address answers 409 IP_WHITELISTED; the caller's own address, or a network covering it, answers 422 SELF_LOCKOUT.

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `ip` | string | yes | — |
| `jail_name` | string | yes | — |

**Request body example:**

```json
{
  "ip": "string",
  "jail_name": "string"
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `MessageResponse` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "message": "string",
  "status": "success"
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/fail2ban/ban
```

---

<a id="delete-api-v1-fail2ban-ban-jail-name-ip"></a>
#### `DELETE /api/v1/fail2ban/ban/{jail_name}/{ip}`

*Unban single IP from a jail*

Removes the IP from the named jail. Other jails are unaffected.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `jail_name` | string | yes | — |
| `ip` | string | yes | — |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `MessageResponse` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "message": "string",
  "status": "success"
}
```

**cURL example:**

```bash
curl -X DELETE \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/fail2ban/ban/{jail_name}/{ip}
```

---

<a id="get-api-v1-fail2ban-banned"></a>
#### `GET /api/v1/fail2ban/banned`

*List currently banned IPs*

Aggregated banned list across every enabled jail.

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_list_BannedIPEntry__` | Successful Response |

**Response example (200):**

```json
{
  "data": [
    {
      "ip": "...",
      "jail": "..."
    }
  ],
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/fail2ban/banned
```

---

<a id="get-api-v1-fail2ban-jails"></a>
#### `GET /api/v1/fail2ban/jails`

*List fail2ban jails*

Every jail definition (enabled + disabled), with current banned IP count.

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_list_JailStatusResponse__` | Successful Response |

**Response example (200):**

```json
{
  "data": [
    {
      "banned_ips": "...",
      "bantime": "...",
      "currently_banned": "...",
      "enabled": "...",
      "filter": "...",
      "findtime": "...",
      "logpath": "...",
      "maxretry": "...",
      "name": "...",
      "total_banned": "..."
    }
  ],
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/fail2ban/jails
```

---

<a id="get-api-v1-fail2ban-jails-jail-name"></a>
#### `GET /api/v1/fail2ban/jails/{jail_name}`

*Get fail2ban jail by name*

Detail view of one jail — filters, action, banned list.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `jail_name` | string | yes | — |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_JailStatusResponse_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "banned_ips": [
      "..."
    ],
    "bantime": 0,
    "currently_banned": 0,
    "enabled": false,
    "filter": "string",
    "findtime": 0,
    "logpath": "string",
    "maxretry": 0,
    "name": "string",
    "total_banned": 0
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/fail2ban/jails/{jail_name}
```

---

<a id="put-api-v1-fail2ban-jails-jail-name"></a>
#### `PUT /api/v1/fail2ban/jails/{jail_name}`

*Update fail2ban jail*

Patch maxretry / findtime / bantime / log paths.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `jail_name` | string | yes | — |

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `bantime` | integer | no | — |
| `findtime` | integer | no | — |
| `maxretry` | integer | no | — |

**Request body example:**

```json
{
  "bantime": 60.0,
  "findtime": 60.0,
  "maxretry": 1.0
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_JailStatusResponse_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "banned_ips": [
      "..."
    ],
    "bantime": 0,
    "currently_banned": 0,
    "enabled": false,
    "filter": "string",
    "findtime": 0,
    "logpath": "string",
    "maxretry": 0,
    "name": "string",
    "total_banned": 0
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X PUT \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/fail2ban/jails/{jail_name}
```

---

<a id="post-api-v1-fail2ban-jails-jail-name-disable"></a>
#### `POST /api/v1/fail2ban/jails/{jail_name}/disable`

*Disable fail2ban jail*

Deactivates the jail and reloads fail2ban. Existing bans on the jail are released.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `jail_name` | string | yes | — |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `MessageResponse` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "message": "string",
  "status": "success"
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/fail2ban/jails/{jail_name}/disable
```

---

<a id="post-api-v1-fail2ban-jails-jail-name-enable"></a>
#### `POST /api/v1/fail2ban/jails/{jail_name}/enable`

*Enable fail2ban jail*

Activates the jail and reloads fail2ban.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `jail_name` | string | yes | — |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `MessageResponse` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "message": "string",
  "status": "success"
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/fail2ban/jails/{jail_name}/enable
```

---

<a id="get-api-v1-fail2ban-status"></a>
#### `GET /api/v1/fail2ban/status`

*Fail2Ban service status*

Returns whether fail2ban daemon is running, version, jail count, total banned IPs.

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_Fail2BanStatusResponse_` | Successful Response |

**Response example (200):**

```json
{
  "data": {
    "active": false,
    "jail_count": 0,
    "jails": [
      "..."
    ],
    "total_banned": 0,
    "version": ""
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/fail2ban/status
```

---

<a id="post-api-v1-fail2ban-unban-all"></a>
#### `POST /api/v1/fail2ban/unban-all`

*Unban every IP across every jail*

Bulk action — clears every active ban in every jail. Whitelist is untouched. The message carries the number of released addresses.

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `MessageResponse` | Successful Response |

**Response example (200):**

```json
{
  "message": "string",
  "status": "success"
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/fail2ban/unban-all
```

---

<a id="get-api-v1-fail2ban-whitelist"></a>
#### `GET /api/v1/fail2ban/whitelist`

*Get fail2ban whitelist*

IPs permanently exempt from every jail's ban logic. Response data: a list of whitelisted IP strings.

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_list_str__` | Successful Response |

**Response example (200):**

```json
{
  "data": [
    "string"
  ],
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/fail2ban/whitelist
```

---

<a id="post-api-v1-fail2ban-whitelist"></a>
#### `POST /api/v1/fail2ban/whitelist`

*Add IP to whitelist*

Exempt an IP from all fail2ban bans. Existing bans on the IP are released.

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `ip` | string | yes | — |

**Request body example:**

```json
{
  "ip": "string"
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `MessageResponse` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "message": "string",
  "status": "success"
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/fail2ban/whitelist
```

---

<a id="delete-api-v1-fail2ban-whitelist-ip"></a>
#### `DELETE /api/v1/fail2ban/whitelist/{ip}`

*Remove IP from whitelist*

The IP returns to normal ban-eligible state.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `ip` | string | yes | — |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `MessageResponse` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "message": "string",
  "status": "success"
}
```

**cURL example:**

```bash
curl -X DELETE \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/fail2ban/whitelist/{ip}
```

---