Ubiquiti EdgeOS Go Client

2026-01-04 13:26:40 -05:00
commit e0c0321bc9
7 changed files with 1076 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,143 @@
+# edgeos
+
+A Go client library for interacting with Ubiquiti EdgeOS devices (specifically tested with EdgeSwitch XP / ToughSwitch) via their internal REST API.
+
+**⚠️ Disclaimer: This library is based on reverse-engineered API calls. It is not an official Ubiquiti product and is subject to change if the device firmware changes.**
+
+## Features
+
+- **Authentication**: Handles login and session token management automatically.
+- **Multi-Device Support**: Manage multiple devices with a single client instance.
+- **Data Retrieval**:
+  - **System Information**: Hostname, uptime, firmware version, etc.
+  - **Interfaces**: Status, POE settings, link speed, statistics.
+  - **VLANs**: Configuration and trunk information.
+  - **Services**: SSH, Telnet, Web Server, NTP, SNMP, etc.
+  - **Statistics**: Real-time throughput, errors, and resource usage.
+  - **Discovery**: Neighbor discovery via UBNT protocol.
+
+## Installation
+
+```bash
+go get gitea.libretechconsulting.com/rmcguire/edgeos-client/pkg/edgeos
+```
+
+## Usage
+
+### Basic Example
+
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"time"
+
+	"gitea.libretechconsulting.com/rmcguire/edgeos-client/pkg/edgeos"
+)
+
+func main() {
+	ctx := context.Background()
+
+	// Configure your device(s)
+	configs := []edgeos.Config{
+		{
+			Host:     "192.168.1.1",
+			Username: "ubnt",
+			Password: "password",
+			Insecure: true, // Set to true if using self-signed certs
+			Timeout:  10 * time.Second,
+		},
+	}
+
+	// Initialize the client
+	client := edgeos.MustNew(ctx, configs)
+
+	// Fetch system information
+	deviceHost := "192.168.1.1"
+	system, err := client.GetSystem(ctx, deviceHost)
+	if err != nil {
+		log.Fatalf("Failed to get system info: %v", err)
+	}
+
+	fmt.Printf("Connected to: %s (Timezone: %s)\n", system.Hostname, system.Timezone)
+
+	// Fetch interfaces
+	ifaces, err := client.GetInterfaces(ctx, deviceHost)
+	if err != nil {
+		log.Fatalf("Failed to get interfaces: %v", err)
+	}
+
+	for _, iface := range ifaces {
+		fmt.Printf("Interface %s: %s (POE: %s)\n", 
+			iface.Identification.ID, 
+			iface.Status.Speed, 
+			iface.Port.POE,
+		)
+	}
+}
+```
+
+### Retrieving Statistics
+
+```go
+stats, err := client.GetStatistics(ctx, "192.168.1.1")
+if err != nil {
+    log.Fatal(err)
+}
+
+for _, stat := range stats {
+    // Device level stats
+    fmt.Printf("CPU Usage: %d%%\n", stat.Device.CPU[0].Usage)
+    
+    // Per-interface stats
+    for _, iface := range stat.Interfaces {
+        fmt.Printf("[%s] Rx: %d bps, Tx: %d bps\n", 
+            iface.Name,
+            iface.Statistics.RxRate,
+            iface.Statistics.TxRate,
+        )
+    }
+}
+```
+
+### Working with Multiple Devices
+
+The client is designed to handle multiple devices concurrently.
+
+```go
+configs := []edgeos.Config{
+    {Host: "192.168.1.1", ...},
+    {Host: "192.168.1.2", ...},
+}
+client := edgeos.MustNew(ctx, configs)
+
+// Get info for all configured devices in parallel
+allSystems, err := client.GetAllSystems(ctx)
+if err != nil {
+    // Note: This returns partial results if available, check implementation
+    log.Printf("Error fetching some systems: %v", err)
+}
+
+for host, sys := range allSystems {
+    fmt.Printf("[%s] Hostname: %s\n", host, sys.Hostname)
+}
+```
+
+## Supported Endpoints
+
+| Method | Description |
+|--------|-------------|
+| `GetSystem` | General system configuration and status |
+| `GetInterfaces` | Interface configuration and status |
+| `GetVLANs` | VLAN and Trunk configuration |
+| `GetServices` | State of running services (SSH, NTP, etc.) |
+| `GetStatistics` | Performance metrics |
+| `GetNeighbors` | Discovered UBNT neighbors |
+| `GetDevice` | Hardware and capabilities info |
+
+## License
+
+MIT