# poddmo/ufw-blocklist architecture

> Architecture diagram of the GitHub repository poddmo/ufw-blocklist, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/poddmo/ufw-blocklist
- Repository: https://github.com/poddmo/ufw-blocklist

## Overview

ufw-blocklist is a small Ubuntu firewall extension: UFW lifecycle commands manage kernel blocklist rules, while a daily job refreshes the IPsum list. The documented operational path is UFW start/reload, with the blocklist applied to inbound, outbound, and forwarded traffic; administrators can also inspect status or flush the set. The README documents the update source and scheduling, but no source excerpts were provided, so implementation-level calls and the role of after.init_run-parts are not inferred.

Main entry points: [`after.init`](https://github.com/poddmo/ufw-blocklist/blob/main/after.init) (UFW hook), [`ufw-blocklist-ipsum`](https://github.com/poddmo/ufw-blocklist/blob/main/ufw-blocklist-ipsum) (IPsum updater)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lifecycle["UFW lifecycle"]
  node_init["UFW hook<br/>[after.init]"]
  node_runparts["Run-parts hook"]
end

subgraph group_refresh["Blocklist refresh"]
  node_updater["IPsum updater"]
end

subgraph group_filtering["Packet filtering"]
  node_set[("Kernel ipset")]
  node_firewall["UFW firewall rules<br/>[after.init]"]
  node_logs["System logs"]
end

node_admin(("Administrator"))
node_ufw["UFW"]
node_scheduler["Daily scheduler"]
node_ipsum["IPsum list"]
node_traffic(("Network packets"))

node_ufw -->|"starts / reloads"| node_init
node_admin -->|"requests status / flush"| node_init
node_scheduler -->|"runs daily"| node_updater
node_updater -->|"downloads list"| node_ipsum
node_updater -->|"refreshes entries"| node_set
node_init -->|"manages set"| node_set
node_init -->|"installs rules"| node_firewall
node_traffic -->|"matches packets"| node_firewall
node_firewall -->|"matches addresses"| node_set
node_firewall -->|"logs selected drops"| node_logs
node_admin -->|"manually adds IPs"| node_set
node_init -->|"reports status / flushes"| node_set

click node_init "https://github.com/poddmo/ufw-blocklist/blob/main/after.init"
click node_runparts "https://github.com/poddmo/ufw-blocklist/blob/main/after.init_run-parts"
click node_updater "https://github.com/poddmo/ufw-blocklist/blob/main/ufw-blocklist-ipsum"
click node_firewall "https://github.com/poddmo/ufw-blocklist/blob/main/after.init"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_init,node_runparts toneBlue
class node_updater toneAmber
class node_set,node_firewall,node_logs toneMint
class node_admin,node_ufw,node_ipsum,node_traffic toneIndigo
class node_scheduler toneRose
```

## Components

### UFW lifecycle

- [UFW hook](https://github.com/poddmo/ufw-blocklist/blob/main/after.init): `after.init`
- [Run-parts hook](https://github.com/poddmo/ufw-blocklist/blob/main/after.init_run-parts): `after.init_run-parts`

### Blocklist refresh

- [IPsum updater](https://github.com/poddmo/ufw-blocklist/blob/main/ufw-blocklist-ipsum): `ufw-blocklist-ipsum`

### Packet filtering

- **Kernel ipset**
- [UFW firewall rules](https://github.com/poddmo/ufw-blocklist/blob/main/after.init): `after.init`
- **System logs**

### Other components

- **Administrator**
- **UFW**
- **Daily scheduler**
- **IPsum list**
- **Network packets**

## Connections

- UFW → UFW hook: starts / reloads
- Administrator → UFW hook: requests status / flush
- Daily scheduler → IPsum updater: runs daily
- IPsum updater → IPsum list: downloads list
- IPsum updater → Kernel ipset: refreshes entries
- UFW hook → Kernel ipset: manages set
- UFW hook → UFW firewall rules: installs rules
- Network packets → UFW firewall rules: matches packets
- UFW firewall rules → Kernel ipset: matches addresses
- UFW firewall rules → System logs: logs selected drops
- Administrator → Kernel ipset: manually adds IPs
- UFW hook → Kernel ipset: reports status / flushes