FAQ

This page answers the questions that come up most often - before you install, when you are evaluating, and when you are deciding whether to take FreeSDN to production.

---

Licensing and cost

Is FreeSDN free?

The platform itself is free to download, run, and modify. There are no per-device fees, no usage metering, and no phone-home telemetry. You own the install.

The word “free” has two meanings here. The core platform is free as in freedom: it is licensed under AGPL-3.0-only, which means you can read, run, and modify the code, but any modified version you distribute or run as a public network service must also be released under AGPL-3.0. The separate freesdn-agent desktop/daemon package is MIT.

There is no SaaS tier, no cloud dependency, and no hosted version. FreeSDN is a self-hosted product only.

License - AGPL-3.0, not MIT

The core platform is AGPL-3.0-only. An older version of this site incorrectly stated MIT. If your use case requires a proprietary fork or service-without-source-disclosure, consult a lawyer before building on FreeSDN.

What does AGPL mean in practice?

For most private operators - running FreeSDN to manage your own network - AGPL has no practical consequence. You can modify it as you like for internal use.

AGPL’s extra obligation compared with GPL kicks in if you offer FreeSDN (or a modified version of it) as a service to third parties over a network. In that case, recipients of the service must be able to obtain the corresponding source code. If you are building a managed-service product on top of FreeSDN, review the license carefully.

Are there per-device fees?

No. There is no licensing tier based on device count, site count, or user count. The optional organization-quota system exists in the codebase (for a hypothetical SaaS deployment) but it is disabled by default (ENFORCE_ORG_QUOTAS=false). A self-hosted install is effectively unlimited.

---

Production readiness

Is FreeSDN production-ready?

The core platform ships with the following validation:

• Automated security regression tests under backend/tests/security/test_pentest_*.py covering tenant isolation, privilege escalation, secret redaction, SSRF, and authentication-flow edge cases.
• Internal review across modules, end-to-end functionality, the enterprise surface, release stability, and core invariants.
• Live battle-test at 25 simulated organizations / 2,000 devices: chaos (worker-kill, Valkey failure, Postgres faults, recovery) and load (0 5xx, rate-limiting functional, tenant isolation held) both passed.
• CI now gates the main branch.

The result is a codebase with a coherent authorization model, no known injection vectors, and hardened multi-tenancy. Note that this has been tested in only a small number of local environments - evaluate it on its merits for your own deployment.

No third-party certification

FreeSDN has no SOC 2, ISO 27001, or other compliance certification, and no third-party security audit is claimed. The validation above is real and documented, but it is not a substitute for a formal compliance program if your organization requires one.

Beta modules

Two modules are explicitly beta and off by default: Access Control and AI Assistant. See the sections below. Do not rely on either for safety-critical or production-gating workflows without independent testing.

What parts are still beta?

Module	Status	Honest caveat
Access Control	Beta, off by default	Door lock/unlock endpoints return 501 Not Implemented - no door adapter ships yet. CRUD for doors, cardholders, credentials, and schedules works, but no hardware control.
AI Assistant	Beta, off by default	Multi-provider LLM assistant with 11 tools. Functional, but the agentic loop and governance model are still being proven in field deployments.
freesdn-agent desktop/daemon	Alpha (v1.0.0, MIT)	Stable for discovery and passive listeners; the auto-update and command surface are under active development.

SAML SSO is also gated at 501. The current parser is vulnerable to XML Signature Wrapping: a forged unsigned assertion can be wrapped around a legitimately-signed one, which validate_sign() does not detect. OIDC and LDAP SSO are fully working.

No working door control

The Access Control module does not control physical doors in this release. The 501 gate is intentional. Do not install FreeSDN and expect to unlock doors.

---

Video surveillance

Does FreeSDN record video?

FreeSDN manages cameras and NVRs - it does not replace your NVR. Live streams (RTSP/HLS/MJPEG/fMP4), snapshots, PTZ, and recording playback are all supported by reading from the NVR. Recordings are stored on the NVR itself.

What FreeSDN adds on top of NVR management:

• Forensic export - watermarked clip export with SHA-256 hash for evidence integrity.
• Legal hold - durable off-NVR archive copy (SHA-256 verified, stored under EVIDENCE_DIR).
• LPR event ingestion, camera analytics counters, per-camera ACL enforcement, and automation triggers.

4K HEVC limitation

4K HEVC streams transcode slowly with libx264 and classic NVR models with HEVC-only output cannot be decoded by the platform’s ffmpeg pipeline. This is a documented hardware constraint, not a bug to be filed.

---

Cloud and air-gap

Does FreeSDN require a cloud connection?

No. FreeSDN is fully self-hosted and fully air-gappable. Nothing phones home. There is no activation key, no license server, and no external telemetry endpoint.

Features that optionally reach the internet:

Feature	External destination	Required?
Let’s Encrypt TLS	Let’s Encrypt ACME servers (via Caddy)	No - use localhost or :<port> instead
AI Assistant	OpenAI or Anthropic APIs	No - use Ollama for a fully local model
Plugin marketplace	Publisher-signed catalog	No - unsigned/offline installs are blocked by default, but the feature is optional
Agent auto-update	Your own release server	No - fail-closed if unreachable
Off-site backup (DR profile)	rclone destination of your choice	No - standard pg-backup stays local

The AI governance layer enforces a three-tier policy: global kill-switch (default OFF) → per-org policy (DISABLED / LOCAL_ONLY / CLOUD_APPROVED) → field selector (automation rules declare explicit input_fields; no wildcards). PII redaction runs separately at call time before any cloud provider receives message content. You can use Ollama with LOCAL_ONLY and never send a byte outside your network.

---

Supported vendors

Which vendors does FreeSDN support?

Thirteen adapters are included and auto-registered at startup. Depth varies - see docs/SUPPORTED_VENDORS.md for the complete honesty matrix.

Category	Adapter	Notes
Network	Omada	Gold standard, most complete
Network	UniFi	Beta - 18 read methods, 8 dual-gated writes (PoE, port override, WLAN PSK/toggle, client block/unblock/forget, device restart/disable); not yet tested against real Ubiquiti hardware
Firewall / gateway	OPNsense	Production, , 13 domains including OSPF/BGP
Firewall / gateway	pfSense	Production
Firewall / gateway	MikroTik (RouterOS v7)	Production
Firewall / gateway	OpenWrt	Firewall, DHCP, base config
Cameras	Hikvision	Production, ISAPI
Cameras	ONVIF	Generic shim
Cameras	UniFi Protect	Supported
VoIP	FreePBX	Beta, AMI+ARI+REST
VoIP	Grandstream	Supported
Hypervisor	Proxmox VE	Cluster, nodes, VMs, LXC, snapshots, backups, storage, SDN
Storage	TrueNAS	WS JSON-RPC, ZFS health/alerts/disk temps

Adapter depth varies

“Supported” does not mean feature-parity across all adapters. The Omada adapter is the reference implementation. UniFi, for example, is Beta - covering 18 read methods and 8 dual-gated writes - but has not yet been tested against real Ubiquiti hardware. Check docs/SUPPORTED_VENDORS.md before committing to a deployment based on a specific vendor.

How do write operations work - do they apply immediately?

No, and this is intentional. All vendor write operations go through a staged-write pipeline:

1. You POST a change - it is stored as a pending change in the database.
2. Nothing touches the live device.
3. An operator explicitly applies the change (carrying force=true).

The live-push path requires the ADAPTER_READ_ONLY environment variable to be set to false (it defaults to true). Even then, a write only reaches the device when force=true is passed in the apply call (step 3 above). This means a fresh install that “successfully stages a change” has not yet touched any hardware.

---

Comparison with other NMS tools

How does FreeSDN compare to [NMS X]?

A few honest reference points rather than a feature-checklist marketing comparison:

• Scope: FreeSDN spans network, cameras, VoIP, firewall, access, backup, compute, observability, and AI in a single platform with a unified RBAC model and multi-tenant data isolation. Traditional NMS tools are network-only.
• Architecture: 10 modules, Python 3.14 / FastAPI / PostgreSQL 18 / TimescaleDB / Valkey. No proprietary agents are required; discovery is agentless or via the optional MIT-licensed desktop agent.
• License: AGPL-3.0. Most commercial NMS tools are proprietary. Most well-known open-source NMS tools (LibreNMS, NetBox, etc.) are either MIT or Apache. AGPL means source modifications must be disclosed if you offer it as a service.
• Vendor depth: 13 adapters today, depth varies. If you need comprehensive write automation for a specific vendor, check the honesty matrix first.
• Multi-tenancy: built-in organization/site scoping with a 7-tier role hierarchy and per-user site grants - suited to MSPs or multi-site enterprises. Most open-source NMS tools are single-tenant.

FreeSDN is not the right choice if you need a compliance-certified product (no SOC 2), if you need SAML SSO today, or if your primary hardware is a vendor whose adapter is a skeleton.

---

Security and authentication

What authentication methods are supported?

Method	Status
Username / password (Argon2id, min 12 chars)	Working
TOTP MFA (+ 8-char backup codes)	Working
OIDC SSO	Working
LDAP SSO	Working
SAML SSO	501-gated, not available
Scoped API keys (hard permission ceiling)	Working
OAuth2 authorization-code server (FreeSDN as IdP)	Working

Password hashing uses Argon2id with 64 MB memory, t=3, p=4. Account lockout engages after 5 failed attempts (30-minute lock). All auth endpoints are rate-limited (5/min per IP, 20 failures per 5 minutes per username).

SAML is disabled

SAML SSO returns 501 in this release. Use OIDC or LDAP if you need SSO.

Is multi-tenancy enforced at the database layer (PostgreSQL RLS)?

No. Multi-tenancy is enforced at the application layer: queries are org-scoped by the service layer, and endpoints pass through permission checks, with per-user site-grant checks enforced across the site-scoped modules. The isolation model is fail-closed - unknown access level → deny.

No PostgreSQL RLS

FreeSDN does not use PostgreSQL Row-Level Security. The boundary is the application layer. A bug in the application layer that bypassed org-scoping would not be stopped by the database. The security controls and automated tests above represent significant effort to prevent such bugs, but you should understand the architecture boundary.

---

AI Assistant

How do I enable the AI Assistant?

The AI module is beta and disabled globally by default. To enable it:

1. Set LLM_GLOBALLY_ENABLED=true in your environment (or .env file).
2. Configure at least one provider in the Admin UI: go to Settings → AI Policy → Providers for your organisation. Enter the API key for OpenAI or Anthropic there - credentials are encrypted in the database and are not set via environment variables. For Ollama, set the base URL (default http://localhost:11434) in the same screen - no API key is required.
3. In the Admin panel, set the per-organization AI policy to LOCAL_ONLY (Ollama only) or CLOUD_APPROVED (allows OpenAI/Anthropic calls).

The global kill-switch takes precedence over all org policies. PII redaction runs before any cloud provider call regardless of policy setting.

The AI assistant has 11 tools (device queries, alert summaries, network/VLAN reads, bandwidth stats, log search, automation rules, etc.) and runs an agentic loop capped at 5 iterations. No vendor SDK is used - provider calls go over plain httpx.

---

High availability

What is the HA story?

FreeSDN includes a documented HA overlay (docker-compose.ha.yml, part of the max scale tier).

Component	Failover type
Valkey (cache / broker)	Automatic - master + replica + 3 Sentinels; ~9-14s promotion observed in drills
PostgreSQL	Manual - streaming standby; promotion requires operator action
API workers	Active-active replicas behind nginx round-robin

PostgreSQL failover is manual

Automatic Postgres failover (Patroni-style) is not available in this release. If your primary Postgres goes down, you must manually promote the standby. Plan your RTO accordingly.

The full Valkey Sentinel HA setup (central redis_client factory with master re-resolution, auth, resolve-hostnames, socket_timeout fail-fast) is live-proven. See the deployment guide for configuration details.

---

Reporting bugs and security issues

How do I report a bug?

For general bugs, open an issue on the GitHub repository. Include:

1. FreeSDN version (APP_VERSION from GET /api/v1/health/detail - requires authentication - or the Admin → About page).
2. Scale tier and any non-default environment flags.
3. Steps to reproduce, observed behavior, expected behavior.
4. Relevant log lines (from docker compose logs api or docker compose logs worker).

How do I report a security vulnerability?

Do not open a public GitHub issue for security findings. Follow the responsible disclosure process in SECURITY.md in the repository root. The project maintainers aim to acknowledge reports within 72 hours and provide a remediation timeline.

The platform’s security model and remediation posture are documented on the security pages. Regression tests under backend/tests/security/test_pentest_*.py pin the reported findings.

---

Next steps

• Review supported vendors in detail: Supported Vendors
• Understand the role hierarchy and permissions: Security Model
• Deploy for production: Production Deployment
• Configure the AI module: AI Assistant
• Set up SSO (OIDC or LDAP): Single Sign-On