go-netops/specs/unifi.md

unifi

Import: forge.lthn.ai/core/go-netops/unifi Files: 11

Types

Client

Wraps the underlying *github.com/unpoller/unifi/v5.Unifi client together with the controller URL used to create it. The struct has no exported fields.

Methods:

• API() *uf.Unifi: Returns the underlying SDK client stored on the wrapper.
• URL() string: Returns the controller URL captured when the client was constructed.
• GetClients(filter ClientFilter) ([]*uf.Client, error): Resolves the requested site scope with GetSites, fetches clients from the SDK, and optionally filters the result by wired or wireless state using uf.Client.IsWired.Val.
• GetDevices(siteName string) (*uf.Devices, error): Resolves the site filter and returns the raw *uf.Devices container from the SDK.
• GetDeviceList(siteName, deviceType string) ([]DeviceInfo, error): Flattens the UAPs, USWs, USGs, UDMs, and UXGs slices from *uf.Devices into DeviceInfo values. deviceType accepts uap, usw, usg, udm, or uxg; an empty value includes every supported device group.
• GetNetworks(siteName string) ([]NetworkConf, error): Calls the controller endpoint /api/s/{site}/rest/networkconf directly, defaults an empty site name to default, unmarshals the JSON data payload, and returns the resulting []NetworkConf.
• GetRoutes(siteName string) ([]Route, error): Calls the controller endpoint /api/s/{site}/stat/routing directly, defaults an empty site name to default, path-escapes the site name, unmarshals the JSON data payload, and returns the resulting []Route.
• GetSites() ([]*uf.Site, error): Returns the sites exposed by the controller through the underlying SDK client.

ClientFilter

Controls how (*Client).GetClients scopes and filters client results.

Fields:

• Site string: Site name to query. An empty value means all sites returned by GetSites.
• Wired bool: When true, include wired clients.
• Wireless bool: When true, include wireless clients.

DeviceInfo

Flat infrastructure-device view returned by (*Client).GetDeviceList.

Fields:

• Name string: Device name from the controller.
• IP string: Device IP address.
• Mac string: Device MAC address.
• Model string: UniFi hardware model identifier.
• Version string: Firmware version string.
• Type string: Device family tag populated by this package as uap, usw, usg, udm, or uxg.
• Status int: Raw device state converted with State.Int(). The code treats 1 as online.

NetworkConf

Direct mapping of a UniFi networkconf entry returned by the controller API.

Fields:

• ID string: Raw network identifier from _id.
• Name string: Network name.
• Purpose string: Network purpose such as wan, corporate, or remote-user-vpn.
• IPSubnet string: CIDR subnet string from ip_subnet.
• VLAN int: VLAN ID from vlan. 0 means untagged.
• VLANEnabled bool: Whether VLAN tagging is enabled.
• Enabled bool: Whether the network entry is enabled.
• NetworkGroup string: Raw network group value such as LAN, WAN, or WAN2.
• NetworkIsolationEnabled bool: Whether UniFi network isolation is enabled.
• InternetAccessEnabled bool: Whether internet access is enabled for the network.
• IsNAT bool: Whether NAT is enabled.
• DHCPEnabled bool: Whether the controller DHCP server is enabled for the network.
• DHCPStart string: DHCP range start address.
• DHCPStop string: DHCP range end address.
• DHCPDNS1 string: Primary DHCP DNS server.
• DHCPDNS2 string: Secondary DHCP DNS server.
• DHCPDNSEnabled bool: Whether custom DHCP DNS servers are enabled.
• MDNSEnabled bool: Whether mDNS is enabled.
• FirewallZoneID string: Raw firewall zone identifier.
• GatewayType string: Raw gateway type value.
• VPNType string: Raw VPN type value for VPN networks.
• WANType string: WAN type such as pppoe, dhcp, or static.
• WANNetworkGroup string: Raw WAN network-group value from wan_networkgroup.

Route

Single routing-table entry returned by the controller gateway routing endpoint.

Fields:

• Network string: Route prefix in CIDR form from pfx.
• NextHop string: Next-hop address or interface from nh.
• Interface string: Interface name from intf.
• Type string: Raw route type code from type.
• Distance int: Administrative distance.
• Metric int: Route metric.
• Uptime int: Route uptime in seconds.
• Selected bool: Whether the route is installed in the forwarding table, taken from fib.

This package exports no interfaces or type aliases.

Functions

New(url, user, pass, apikey string, insecure bool) (*Client, error)

Creates a UniFi client from explicit controller settings. It builds a uf.Config, creates the underlying SDK client, replaces its HTTP client with one that enforces TLS 1.2, and sets InsecureSkipVerify when insecure is true.

NewFromConfig(flagURL, flagUser, flagPass, flagAPIKey string, flagInsecure *bool) (*Client, error)

Resolves controller settings through ResolveConfig, requires either a username or an API key to be present, and then delegates to New.

ResolveConfig(flagURL, flagUser, flagPass, flagAPIKey string, flagInsecure *bool) (url, user, pass, apikey string, insecure bool, err error)

Builds the effective controller configuration in three layers: config-file values from forge.lthn.ai/core/config, environment overrides from UNIFI_URL, UNIFI_USER, UNIFI_PASS, UNIFI_APIKEY, and UNIFI_INSECURE, then non-empty flag overrides plus a non-nil flagInsecure. If no URL is resolved, it falls back to DefaultURL. If config.New() fails, the function still returns values from env, flags, and the default URL without surfacing that config-load error.

RouteTypeName(code string) string

Maps UniFi route type codes to human-readable names: S to static, C to connected, K to kernel, B to bgp, and O to ospf. Any other code is returned unchanged.

SaveConfig(url, user, pass, apikey string, insecure *bool) error

Persists non-empty controller settings to the standard config store. The function writes only the values that were provided, writes the insecure flag only when the pointer is non-nil, and commits the config file after all updates succeed.