Key Concepts

Before configuring FreeSDN, understand the six concepts that shape everything else: the hierarchy (Organizations → Sites → Controllers → Devices), Modules, Adapters, the staged-write safety model, roles with site grants, and the Fabric.

The hierarchy

Organization (tenant)
└── Site (a physical location or logical group)
    └── Controller (a management endpoint: Omada SDN, OPNsense, Proxmox, etc.)
        └── Device (switch, AP, camera, phone, VM, …)

Organization

An Organization is the top-level multi-tenancy boundary. Every object - sites, controllers, devices, users, alert rules, automation - belongs to exactly one organization. Users from org A cannot see or affect org B’s data.

A single FreeSDN instance hosts many independent organizations with complete data isolation enforced at the application layer in the service layer.

Application-layer isolation, not database RLS

Multi-tenant isolation is enforced by org-scoped queries throughout the service layer. FreeSDN does not use PostgreSQL Row-Level Security. All enforcement is in the application layer with fail-closed defaults.

Site

A Site is a physical location (a branch office, a data center, a home lab) or any logical grouping that makes sense for your operation. Sites are the unit at which module permissions and user grants are scoped.

A controller belongs to exactly one site. A user can be granted access to a specific subset of sites within an organization rather than the whole organization.

Controller

A Controller is a management endpoint - a running instance of Omada SDN, an OPNsense firewall, a Proxmox cluster, an NVR, a PBX. FreeSDN talks to controllers through vendor Adapters (see below).

One site can have multiple controllers of the same or different types. The Network module’s alignment and distribution features operate across controllers within a site.

Device

Devices are the managed endpoints discovered from controllers: switches, access points, cameras, phones, virtual machines, LXC containers, and so on. FreeSDN shows them in inventory, monitors their state, and lets operators apply configuration changes through the staged-write model.

Modules

Modules are the feature planes of FreeSDN. Each module mounts at its own API prefix (/api/v1/{module-id}/) and is independently enabled or disabled per organization.

Module	API prefix	Status
Network Management	/network/	Production
Video Surveillance	/cameras/	Production
VoIP & Telephony	/voip/	Production
Firewall (incl. gateway orchestration)	/firewall/	Production
Compute / Hypervisor	/hypervisor/	Production
Observability	/collector/	Production
Configuration Backup	/backup/	Production
AI Assistant	/ai/	Beta
Access Control	/access_control/	Coming soon - disabled by default, cannot be enabled yet; data model / RBAC / schema ship, but UI is a placeholder and door lock/unlock returns 501 (no hardware adapter ships in this release)
Storage	(Fabric participant, no HTTP routes)	Preview

Enabling a module for an organization makes its UI pages and API routes active for users of that organization. Disabling it hides the module entirely.

Adapters

An Adapter is a typed vendor driver. It translates FreeSDN’s normalized operations (list devices, push VLAN, update rule, reboot port) into the protocol a specific vendor understands - REST, SOAP/ONVIF, WebSocket JSON-RPC, CLI, AMI, and so on.

FreeSDN ships 12 adapters, auto-registered at startup. Adapter depth varies:

Adapter	Domain	Maturity
Omada	Network (gold standard)	Production
OPNsense	Firewall / gateway brain	Production
pfSense	Firewall / gateway brain	Production
MikroTik (RouterOS v7)	Firewall / gateway brain	Production
Hikvision	Cameras (ISAPI)	Production
ONVIF	Cameras (generic shim)	Production
Proxmox VE	Compute	Production
FreePBX	VoIP (AMI + ARI + REST)	Beta
Grandstream	VoIP / phones	Beta
OpenWrt	Network	Preview
UniFi	Network	Preview (skeleton)
TrueNAS	Storage (WS JSON-RPC)	Preview

The per-adapter capability matrix lives in docs/SUPPORTED_VENDORS.md in the repository. When a vendor capability is not available, the adapter returns a typed “not supported” response rather than silently failing.

The staged-write safety model

FreeSDN’s guiding safety principle: the controller is the authority; FreeSDN never pushes a change to a live device without an explicit operator action.

The flow for a configuration mutation:

1. Read - FreeSDN reads current state from the controller via the adapter.
2. Stage - The operator authors a change in the UI or API. FreeSDN stores it as a pending change in the database. Nothing touches the live device yet.
3. Review - The staged change is visible as a diff. A second authorized operator (or the same operator in a single-user setup) can inspect it.
4. Apply - An explicit apply action pushes the change to the controller via the adapter. The gate refuses (403) when ADAPTER_READ_ONLY is True and the apply call does not carry force=true. ADAPTER_READ_ONLY is the single write-safety switch for the staged-write pipeline and every adapter client - clearing it (false) is all that is required on the env-flag side. Passing force=true satisfies the force side, but this is not recommended as a permanent bypass (see the tip below).

Read-only by default

Out of the box, no adapter writes to a live device. Set ADAPTER_READ_ONLY=false in your configuration to enable live writes. (OMADA_READ_ONLY is a legacy alias, also defaulting to true; it is no longer consulted by the staged-write gate or the adapter clients - only the low-level Omada raw passthrough endpoint still honors it, so leave it unset/true unless you specifically use raw Omada writes.) You can safely connect FreeSDN to a production controller in read-only discovery mode before committing to live management.

This model also applies to the Fabric: every write step in a Fabric Connection is staged and requires per-action sign-off before it touches a device.

Roles and site grants

FreeSDN uses a 5-tier role hierarchy for coarse-grained access plus per-user site grants for fine-grained scoping within an organization.

Role	Level	Can do
super_admin	100	Manage all organizations, system settings, plugin installs
org_admin	60	Manage org settings, modules, controllers
site_admin	40	Manage a site’s controllers and devices
operator	20	Apply staged changes, run operations
viewer	10	Read-only access

Each role can only assign roles strictly lower than its own, preventing privilege escalation. API keys are scoped to act as a hard permission ceiling even for super_admin holders.

Site grants let you give a user operator access on Site A but only viewer access on Site B - or no access at all - within the same organization.

See Roles and Permissions for the full reference.

The Fabric

The Fabric is FreeSDN’s event-driven automation and integration layer. It exposes a single tier-tagged catalog (GET /api/v1/fabric/catalog) listing every operation and event across all modules and adapters - native first-party modules and SDK plugins alike.

Operators author Connections: an inbound event triggers a step chain that can invoke operations, send notifications, log records, or call an outbound webhook. FreeSDN ships an n8n community node (n8n-nodes-freesdn) for integration with n8n workflows.

Key safety properties:

• All write steps in a Connection are staged and require per-action sign-off.
• Inbound webhook ingestion (/fabric/ingest) requires an org-scoped API key.
• Outbound webhook targets are validated against a deny-list (no metadata endpoints, no RFC 1918 / CGNAT / loopback targets by default).

See Fabric for full details.