unifi

package
v0.0.4-alpha.39 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 5, 2026 License: EUPL-1.2 Imports: 9 Imported by: 0

Documentation

Overview

Package unifi provides a thin wrapper around the unpoller/unifi Go SDK for managing UniFi network controllers, devices, and connected clients.

Authentication is resolved from config file, environment variables, or flag overrides:

  1. ~/.core/config.yaml keys: unifi.url, unifi.user, unifi.pass, unifi.apikey
  2. UNIFI_URL + UNIFI_USER + UNIFI_PASS + UNIFI_APIKEY environment variables (override config file)
  3. Flag overrides via core unifi config --url/--user/--pass/--apikey (highest priority)

Index

Constants

View Source 
const (
	// ConfigKeyURL is the config key for the UniFi controller URL.
	ConfigKeyURL = "unifi.url"
	// ConfigKeyUser is the config key for the UniFi username.
	ConfigKeyUser = "unifi.user"
	// ConfigKeyPass is the config key for the UniFi password.
	ConfigKeyPass = "unifi.pass"
	// ConfigKeyAPIKey is the config key for the UniFi API key.
	ConfigKeyAPIKey = "unifi.apikey"
	// ConfigKeyInsecure is the config key for allowing insecure TLS connections.
	ConfigKeyInsecure = "unifi.insecure"

	// DefaultURL is the default UniFi controller URL.
	DefaultURL = "https://10.69.1.1"
)

Variables

This section is empty.

Functions

func ResolveConfig 

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

ResolveConfig resolves the UniFi URL and credentials from all config sources. Flag values take highest priority, then env vars, then config file.

func RouteTypeName 

func RouteTypeName(code string) string

RouteTypeName returns a human-readable name for the route type code.

func SaveConfig 

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

SaveConfig persists the UniFi URL and/or credentials to the config file.

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client wraps the unpoller UniFi client with config-based auth.

func New 

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

New creates a new UniFi API client for the given controller URL and credentials. TLS verification can be disabled via the insecure parameter (useful for self-signed certs on home lab controllers).

func NewFromConfig 

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

NewFromConfig creates a UniFi client using the standard config resolution:

  1. ~/.core/config.yaml keys: unifi.url, unifi.user, unifi.pass, unifi.apikey, unifi.insecure
  2. UNIFI_URL + UNIFI_USER + UNIFI_PASS + UNIFI_APIKEY + UNIFI_INSECURE environment variables (override config file)
  3. Provided flag overrides (highest priority; pass nil to skip)

func (*Client) API 

func (c *Client) API() *uf.Unifi

API exposes the underlying SDK client for direct access.

func (*Client) GetClients 

func (c *Client) GetClients(filter ClientFilter) ([]*uf.Client, error)

GetClients returns connected clients from the UniFi controller, optionally filtered by site and connection type.

func (*Client) GetDeviceList 

func (c *Client) GetDeviceList(siteName, deviceType string) ([]DeviceInfo, error)

GetDeviceList returns a flat list of all infrastructure devices, optionally filtered by device type (uap, usw, usg, udm, uxg).

func (*Client) GetDevices 

func (c *Client) GetDevices(siteName string) (*uf.Devices, error)

GetDevices returns the raw device container for a site (or all sites).

func (*Client) GetNetworks 

func (c *Client) GetNetworks(siteName string) ([]NetworkConf, error)

GetNetworks returns all network configurations from the controller. Uses the raw controller API for the full networkconf data.

func (*Client) GetRoutes 

func (c *Client) GetRoutes(siteName string) ([]Route, error)

GetRoutes returns the active routing table from the gateway for the given site. Uses the raw controller API since unpoller doesn't wrap this endpoint.

func (*Client) GetSites 

func (c *Client) GetSites() ([]*uf.Site, error)

GetSites returns all sites from the UniFi controller.

func (*Client) URL 

func (c *Client) URL() string

URL returns the UniFi controller URL.

type ClientFilter 

type ClientFilter struct {
	Site     string // Filter by site name (empty = all sites)
	Wired    bool   // Show only wired clients
	Wireless bool   // Show only wireless clients
}

ClientFilter controls which clients are returned.

type DeviceInfo 

type DeviceInfo struct {
	Name    string
	IP      string
	Mac     string
	Model   string
	Version string
	Type    string // uap, usw, usg, udm, uxg
	Status  int    // 1 = online
}

DeviceInfo is a flat representation of any UniFi infrastructure device.

type NetworkConf 

type NetworkConf struct {
	ID                      string `json:"_id"`
	Name                    string `json:"name"`
	Purpose                 string `json:"purpose"`      // wan, corporate, remote-user-vpn
	IPSubnet                string `json:"ip_subnet"`    // CIDR (e.g. "10.69.1.1/24")
	VLAN                    int    `json:"vlan"`         // VLAN ID (0 = untagged)
	VLANEnabled             bool   `json:"vlan_enabled"` // Whether VLAN tagging is active
	Enabled                 bool   `json:"enabled"`
	NetworkGroup            string `json:"networkgroup"` // LAN, WAN, WAN2
	NetworkIsolationEnabled bool   `json:"network_isolation_enabled"`
	InternetAccessEnabled   bool   `json:"internet_access_enabled"`
	IsNAT                   bool   `json:"is_nat"`
	DHCPEnabled             bool   `json:"dhcpd_enabled"`
	DHCPStart               string `json:"dhcpd_start"`
	DHCPStop                string `json:"dhcpd_stop"`
	DHCPDNS1                string `json:"dhcpd_dns_1"`
	DHCPDNS2                string `json:"dhcpd_dns_2"`
	DHCPDNSEnabled          bool   `json:"dhcpd_dns_enabled"`
	MDNSEnabled             bool   `json:"mdns_enabled"`
	FirewallZoneID          string `json:"firewall_zone_id"`
	GatewayType             string `json:"gateway_type"`
	VPNType                 string `json:"vpn_type"`
	WANType                 string `json:"wan_type"` // pppoe, dhcp, static
	WANNetworkGroup         string `json:"wan_networkgroup"`
}

NetworkConf represents a UniFi network configuration entry.

type Route 

type Route struct {
	Network   string `json:"pfx"`      // CIDR prefix (e.g. "10.69.1.0/24")
	NextHop   string `json:"nh"`       // Next-hop address or interface
	Interface string `json:"intf"`     // Interface name (e.g. "br0", "eth4")
	Type      string `json:"type"`     // Route type (e.g. "S" static, "C" connected, "K" kernel)
	Distance  int    `json:"distance"` // Administrative distance
	Metric    int    `json:"metric"`   // Route metric
	Uptime    int    `json:"uptime"`   // Uptime in seconds
	Selected  bool   `json:"fib"`      // Whether route is in the forwarding table
}

Route represents a single entry in the UniFi gateway routing table.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.