Network List Sync

Network List Sync resolves hostnames to IPs and keeps provider-managed target lists in sync.

It supports multiple endpoint providers in one deployment, currently:

• UniFi
• Nginx Proxy Manager (NPM)

Features

• Web UI for endpoint, DNS server, and sync job management
• Multi-target jobs (one job can update multiple endpoint/list pairs)
• Provider-aware endpoint model (UniFi and NPM side by side)
• Built-in local authentication with persistent server-side sessions
• First-start admin bootstrap (interactive in UI or via Docker environment)
• Cron scheduling with manual run support
• DNS preview before saving a job
• Hostname plus literal IPv4 and IPv4 CIDR inputs
• External URL list inputs (HTTP/HTTPS), for example Cloudflare IP ranges
• Run history and per-run details
• Single binary with embedded UI and SQLite persistence

Why Use It

Use this when upstream systems publish hostnames or changing IP ranges and you need list-based access control to stay current automatically.

Common examples:

• Probe/monitoring provider IPs that rotate over time
• Third-party integrations with DNS-based endpoints
• Mixed static and dynamic allow-lists

How It Works

1. Add one or more endpoints in the UI.
2. Create a sync job with hostnames/IP inputs.
3. Assign a primary target list and optional additional targets.
4. Run manually or on schedule.
5. The service resolves DNS, computes diffs, updates provider lists, and stores run history.

Before You Start

1. Reachable endpoint URLs for each provider.
2. Credentials/secrets with permission to update target lists.
3. Provider-specific identity value if required:
   • UniFi: site (usually default)
   • NPM: identity/account value used by your environment
4. Existing target list IDs in each provider.
5. Persistent storage for the data directory.

Authentication

This application is protected by login.

• First startup with no users: visiting /login shows an admin account creation form.
• After setup: /login shows a standard sign-in form.
• Sessions are server-side and stored in SQLite.

Docker Initial Admin Bootstrap

To create the first admin account automatically on container startup, set both env vars:

• NLS_INITIAL_ADMIN_USERNAME
• NLS_INITIAL_ADMIN_PASSWORD

If users already exist, these values are ignored.

Quick Start

Docker (Recommended)

Run latest build from main:

docker run --rm -p 8080:8080 \
  -v network-list-sync-data:/data \
  ghcr.io/mstrhakr/network-list-sync:main

Run a stable release:

docker run --rm -p 8080:8080 \
  -v network-list-sync-data:/data \
  ghcr.io/mstrhakr/network-list-sync:v0.1.0

Open http://localhost:8080.

Published platforms: linux/amd64 and linux/arm64.

Docker Compose (Example)

See docs/docker-compose.unraid.yml.

services:
  network-list-sync:
    image: ghcr.io/mstrhakr/network-list-sync:main
    container_name: network-list-sync
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      PUID: "99"
      PGID: "100"
      UMASK: "022"
      NLS_INITIAL_ADMIN_USERNAME: "admin"
      NLS_INITIAL_ADMIN_PASSWORD: "change-this-immediately"
    volumes:
      - /mnt/user/appdata/network-list-sync:/data

Run From Source

go run . -addr :8080

Build Binary

go build -o network-list-sync .
./network-list-sync

Runtime Flags

Environment variables:

Example:

./network-list-sync -addr :9090 -db /var/lib/sync/data.db -log-file ./sync.log

UI Setup Walkthrough

1. Open the app and go to Endpoints.
2. Add at least one endpoint with provider, URL, identity/site, and secret.
3. Test connection and save.
4. Create a new sync job.
5. Choose primary endpoint and primary target list.
6. Add hostnames, IPv4, CIDR, or external URL list entries (one per line).
7. Optionally add additional endpoint/list targets.
8. Save and run the job.
9. Review logs and target list state.

Example input:

# Grafana synthetic probes
synthetics.grafana.net

# Static office egress
203.0.113.10
203.0.113.0/24

# External source list
https://www.cloudflare.com/ips-v4

Operational Tips

1. Validate jobs with manual runs before enabling schedule.
2. Keep data persisted under /data across container upgrades.
3. Use exact release tags in production.
4. Keep endpoint credentials scoped to minimum required permissions.

List optimization and run history

Each sync removes duplicate entries and entries already covered by another exact IP/CIDR range. Jobs can optionally collapse fully covered IPv4 ranges into CIDRs. Collapse preserves the exact address set and only creates /24 or larger networks; the option is off by default. Existing smaller CIDRs are retained as provided.

Run history reports input/unique counts, duplicates and covered entries removed, CIDRs created, and total entries saved. When a run updates a target, its history includes an on-demand view of the exact items sent to that target.

API Endpoints

All /api/* endpoints require an authenticated session.

Endpoints/Instances

Jobs

DNS And Health

Cron Schedule Examples

References

• Maintainer guide: docs/development.md
• Migration notes: docs/generic-migration-plan.md
• UniFi schema reference: docs/reference/unifi-network-10.1.85.json

OIDC Roadmap

The auth layer includes provider abstractions for both password and OIDC flows.

• Current provider: local password (local)
• Planned: OIDC providers can be registered without replacing the existing session model

License

MIT