Settings and Maintenance API

All endpoints require authentication (Basic or JWT). Responses use the envelope {"status": "success", "data": ...} unless noted.

---

List all settings

GET /api/settings

{
  "status": "success",
  "data": [
    { "setting_name": "ssl_bump_enabled", "setting_value": "false" },
    { "setting_name": "cache_size",       "setting_value": "2000"  }
  ]
}

Setting values that are stored encrypted at rest (those whose key contains password, secret, token, or webhook) are decrypted before being returned.

---

Update a single setting

PUT /api/settings/{setting_name}

{ "value": "true" }

The key in the path must consist of alphanumeric characters and underscores only and be no longer than 100 characters. The value is capped at 10 000 characters.

---

Bulk update settings

POST /api/settings

The body is a flat object mapping setting names to their new values:

{
  "ssl_bump_enabled": "true",
  "cache_size": "5000",
  "auto_refresh_enabled": "true"
}

All updates are applied in a single transaction. The same name and value validation applies as for the single-setting endpoint.

---

Default-deny egress

POST /api/settings

{ "egress_default_deny": "true" }

egress_default_deny is a boolean setting (default "false") toggled like any other value through the bulk or single-setting endpoints. It is also exposed as the "Default-deny egress" toggle on the Settings page, next to SSL inspection.

When "false" (the default) behaviour is unchanged: local clients may reach any destination that is not on a blacklist. When "true" the proxy denies all outbound egress from local clients except destinations on an explicit allowlist; everything else is refused with a Squid 403.

The allowlist destinations themselves are not setting values. They are managed through the egress-allowlist endpoints (/api/egress-allowlist), where each entry is either an IP/CIDR or a domain. See the egress allowlist API for details.

---

Health

GET /health
GET /api/health

Returns 200 if the backend is reachable. Authentication is not required.

{ "status": "healthy", "version": "3.4.4" }

---

Database export

GET /api/database/export

Returns a JSON dump of every exported table. Columns named password, secret, or token are replaced with ***REDACTED***. The download is served as Content-Disposition: attachment.

---

Database statistics

GET /api/database/stats

Returns row counts for every exported table along with the file size.

---

Database optimise

POST /api/database/optimize

Runs VACUUM and REINDEX on the SQLite database.

---

Database size

GET /api/database/size

Returns the database file size in bytes.

---

Database reset

POST /api/database/reset

Truncates every exported table except users. Use with care.

---

Reload proxy configuration

POST /api/maintenance/reload-config

Asks the proxy to regenerate squid.conf from the latest blacklist/whitelist files and reload.

This call blocks. It writes a trigger file and then waits up to 8 seconds for the proxy's watchdog to acknowledge what it did, so a client should allow at least that. There are three outcomes, and a 200 does not on its own mean the reload was applied:

HTTP	status	Meaning
200	success	The generator ran, squid accepted the config, and it is live
500	error (code: reload_failed)	The proxy refused the new config and kept the previous one. data.generator_rc and data.reconfigure_rc say which step failed
200	pending	Nothing acknowledged within the timeout — check that the proxy container is running

A caller that treats any 200 as success will read pending as applied.

---

Reload DNS configuration

POST /api/maintenance/reload-dns

Regenerates the dnsmasq blocklist (with whitelist exclusions) and signals the dns container to reload (SIGHUP).

---

Cache statistics

GET /api/cache/statistics

Returns Squid cache metrics (hit ratio, memory and disk usage). When the Squid cache manager is unavailable, the response is annotated with simulated: true and zeroed values.

---

Clear proxy cache

POST /api/maintenance/clear-cache

Clears the Squid disk cache.

---

Backup configuration

GET /api/maintenance/backup-config

Downloads a backup containing the current settings, blacklists, and whitelists in JSON form.

---

Restore configuration

POST /api/maintenance/restore-config

Restores from a backup created by /api/maintenance/backup-config.

List entries are checked with the same rules as the endpoints that add them. An entry that fails is skipped, not fatal, and the response reports how many in skipped_entries (alongside restored and skipped, which count settings).

---

Check certificate security

GET /api/maintenance/check-cert-security

Reports the strength and validity of the SSL bump certificate.

---

Download CA certificate

GET /api/security/download-ca

Returns /config/ssl_cert.pem. Install it on client devices to suppress browser warnings when SSL bump is active.

---

Rate limits

GET /api/security/rate-limits

Lists IPs currently locked out by the login-failure rate limiter, with the time at which the lockout expires.

DELETE /api/security/rate-limits/{ip}

Removes the lockout for the given IP.