go-netops

UniFi network controller management for Go.


Module	`forge.lthn.ai/core/go-netops`
Go	1.25.5
Licence	EUPL-1.2
Source	forge.lthn.ai/core/go-netops

Overview

go-netops provides a thin wrapper around the unpoller/unifi Go SDK for managing UniFi network controllers. It handles device discovery, client enumeration, site management, network configuration retrieval, routing table inspection, and multi-source config resolution.

The package is designed for infrastructure automation, monitoring dashboards, and CLI tooling — providing a cleaner API over the raw UniFi controller REST endpoints.

Package Structure

Package	Import Path	Purpose
`unifi`	`forge.lthn.ai/core/go-netops/unifi`	UniFi client, device/client/site/network/route management, config resolution

Dependencies

forge.lthn.ai/core/go — Core framework (logging, config)
github.com/unpoller/unifi/v5 — UniFi controller SDK

Quick Start

package main

import (
    "fmt"
    "log"

    "forge.lthn.ai/core/go-netops/unifi"
)

func main() {
    // Create client using config file, env vars, or flags
    client, err := unifi.NewFromConfig("", "", "", "", nil)
    if err != nil {
        log.Fatal(err)
    }

    // List all sites
    sites, err := client.GetSites()
    if err != nil {
        log.Fatal(err)
    }
    for _, site := range sites {
        fmt.Printf("Site: %s\n", site.Name)
    }

    // List all devices
    devices, err := client.GetDeviceList("", "")
    if err != nil {
        log.Fatal(err)
    }
    for _, d := range devices {
        fmt.Printf("%-20s %-15s %-8s %s\n", d.Name, d.IP, d.Type, d.Version)
    }
}

API Overview

Function / Method	Description
`New(url, user, pass, apikey, insecure)`	Create client with explicit credentials
`NewFromConfig(flagURL, flagUser, flagPass, flagAPIKey, flagInsecure)`	Create client with multi-source config resolution
`ResolveConfig(flags...)`	Resolve config from file, env, and flags
`SaveConfig(url, user, pass, apikey, insecure)`	Persist credentials to config file
`client.GetSites()`	List all controller sites
`client.GetDevices(siteName)`	Get raw device container for a site
`client.GetDeviceList(siteName, deviceType)`	Get flat device list with optional type filter
`client.GetClients(filter)`	Get connected clients with optional filters
`client.GetNetworks(siteName)`	Get network configurations
`client.GetRoutes(siteName)`	Get gateway routing table
`client.API()`	Access the underlying unpoller SDK client
`client.URL()`	Get the controller URL

Device Types

Code	Name	Description
`uap`	Access Point	UniFi wireless access points
`usw`	Switch	UniFi managed switches
`usg`	Security Gateway	UniFi security gateways
`udm`	Dream Machine	UniFi Dream Machine (all-in-one)
`uxg`	Next-Gen Gateway	UniFi next-generation gateways