Filter Subscriptions
Subscribe to external IP/CIDR blocklists that automatically sync and integrate with Nginx.
Overview
A single home server is constantly probed by scanners, brute-force bots, and known malicious networks. Maintaining a blocklist by hand does not scale. Filter Subscriptions let you point Nginx Proxy Guard at community-maintained IP/CIDR blocklists. The system fetches each list on a schedule, deduplicates the entries, and feeds them into Nginx so the listed addresses are blocked at the proxy.
How It Works
| Step | Behavior |
|---|---|
| Subscribe | Add a list by URL, or pick one from the built-in catalog |
| Fetch | The list is downloaded over HTTPS and parsed into IP/CIDR entries |
| Deduplicate | Entries are deduplicated within the list and across other subscriptions and banned IPs |
| Apply | The merged entries are written into the Nginx configuration and reloaded |
| Refresh | The list is re-fetched automatically on its refresh schedule |
Adding a Subscription
You can add a subscription two ways.
| Method | Description |
|---|---|
| From the catalog | Choose a preset blocklist curated for NPG and subscribe with one click |
| By URL | Provide the URL of any external IP/CIDR list |
The catalog is served from the official npg-filters repository, so the preset lists are kept up to date without any manual configuration.
Auto-Refresh Scheduling
Each subscription has its own refresh schedule, so lists that change often can be polled more frequently than stable ones.
| Setting | Description | Default |
|---|---|---|
| Refresh type | How the refresh cadence is interpreted (e.g. interval) | interval |
| Refresh value | How often the list is re-fetched | 24h |
A background scheduler periodically checks every enabled subscription and re-fetches the ones whose refresh interval has elapsed. You can also trigger an immediate Refresh on any subscription from its detail view without waiting for the scheduler.
Deduplication
Blocklists overlap heavily, and a duplicated entry wastes Nginx resources for no benefit. NPG deduplicates on two levels:
- Within a subscription — identical entries in the same list are collapsed.
- Across sources — entries already present in another subscription or in your banned IPs are not duplicated.
This keeps the effective blocklist compact even when you subscribe to several overlapping sources.
Exclusions
Sometimes a blocklist is a little too aggressive for a specific service. NPG supports two kinds of exclusions.
| Exclusion type | Scope | Use case |
|---|---|---|
| Per-host exclusion | A proxy host is exempted from a subscription | A list blocks an IP range your partners use, but only for one app |
| Entry exclusion | A specific IP/CIDR is removed from a subscription | A single false-positive entry blocks a legitimate client |
Per-host exclusions are managed against the subscription and reference the proxy host; entry exclusions remove a specific value from the applied set.
Tip: Prefer an entry exclusion when one address is wrong, and a per-host exclusion when an entire service needs to bypass a list.
Private IP Handling
Each subscription has an exclude private IPs option. When enabled, private/internal address ranges that appear in a list are dropped before the entries are applied, so an over-broad public blocklist cannot accidentally cut off your LAN or Docker network.
Limits
To protect Nginx performance and memory, the system enforces hard limits on blocklist size.
| Limit | Value |
|---|---|
| Entries per list | 25,000 |
| Total entries (all subscriptions) | 100,000 |
| Max download size per list | 10 MB |
If a list exceeds the per-list limit, only the first 25,000 entries are applied. If adding a list would push the combined total past 100,000, it is truncated so the global cap is respected.
Where to Find It
Filter Subscriptions are managed from their own page in the dashboard. From there you can:
- Browse the preset catalog and subscribe
- Add a custom list by URL
- Trigger an immediate refresh
- Review fetched entries and the last sync status
- Manage per-host and per-entry exclusions