wnc

README

cisco-ios-xe-wireless-go

A Go SDK for interacting with Cisco Catalyst 9800 Wireless Network Controller.

✨️ Key Features

• 🔧 Developer-Friendly: Seamless YANG model handling with responses consistently in JSON
• 🚀 Fast Integration: Start in minutes with straightforward setup and clear examples
• 📊 Broad Coverage: Access most configurations and statistics provided by the WNC
• 🎯 Type-Safe Operations: Strongly typed Go structs for reliable API calls and responses
• 📖 Detailed Documentation: Detailed API references, testing guides, and best practices via godoc

📡 Supported Environment

Cisco Catalyst 9800 Wireless Network Controller running on:

• Cisco IOS-XE 17.12.x - Verified on 17.12.6a
• Cisco IOS-XE 17.15.x - Verified on 17.15.4b (Experimental: Spaces)
• Cisco IOS-XE 17.18.x - Verified on 17.18.1 (Experimental: URWB, WAT)

📦 Installation

go get github.com/umatare5/cisco-ios-xe-wireless-go

🚀 Quick Start

You have to enable RESTCONF and HTTPS on the C9800 before using this SDK. Please see:

• Cisco IOS XE 17.12 Programmability Configuration Guide — RESTCONF

1. Generate a Basic Auth token

Encode your controller credentials as Base64.

# username:password → Base64
echo -n "admin:your-password" | base64
# Output: YWRtaW46eW91ci1wYXNzd29yZA==

2. Create a sample application

Use your controller host and token to fetch AP operational data.

package main

import (
    "context"
    "fmt"
    "os"
    "time"

    wnc "github.com/umatare5/cisco-ios-xe-wireless-go"
)

func main() {
    // Load environment variables
    controller := os.Getenv("WNC_CONTROLLER")
    token := os.Getenv("WNC_ACCESS_TOKEN")

    // Create client
    client, err := wnc.NewClient(controller, token,
        wnc.WithTimeout(30*time.Second),
        wnc.WithInsecureSkipVerify(true), // remove for production
    )
    if err != nil {
        fmt.Fprintf(os.Stderr, "Failed to create client: %v\n", err)
        os.Exit(1)
    }

    // Create simple context with timeout
    ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
    defer cancel()

    // Request AP operational data
    apData, err := client.AP().GetOperational(ctx)
    if err != nil {
        fmt.Fprintf(os.Stderr, "AP oper request failed: %v\n", err)
        os.Exit(1)
    }

    // Print AP operational data
    fmt.Printf("Successfully connected! Found %d APs\n",
        len(apData.CiscoIOSXEWirelessAPOperData.CAPWAPData))
}

[!CAUTION] The wnc.WithInsecureSkipVerify(true) option disables TLS certificate verification. This should only be used in development environments or when connecting to controllers with self-signed certificates. Never use this option in production environments as it compromises security.

3. Run the application with environment variables

# Set environment variables
export WNC_CONTROLLER="wnc1.example.internal"
export WNC_ACCESS_TOKEN="YWRtaW46eW91ci1wYXNzd29yZA=="

# Run the application
go run main.go

# result: Successfully connected! Found 2 APs

🌐 API Reference

This SDK provides a client to interact with the Cisco Catalyst 9800 Wireless Network Controller's RESTCONF.

Client Initialization

To create a new client, use the wnc.NewClient function with the controller address and access token.

Parameter	Type	Description
controller	string	The hostname or IP address of the WNC.
accessToken	string	The Base64-encoded Basic Auth token.
options...	...Option	Optional client configuration options.

Client Options

There are several options to customize the client behavior.

Option	Type	Default	Description
WithTimeout(d)	time.Duration	60s	Sets HTTP request timeout.
WithInsecureSkipVerify(b)	bool	false	Skips TLS verify.
WithLogger(l)	*slog.Logger	slog.Default()	Sets structured logger.
WithUserAgent(ua)	string	wnc-go-client/1.0	Custom User-Agent.

Supported Services

Please refer to the Go Reference for the complete reference.

The following table summarizes the supported service APIs and their capabilities.

Legend:

• ✅️ Supported
• 🟩 Partial Supported
• 🟨 Experimental Supported
• ⬜️ Not Supported

API	GetOperational()	GetConfig()	Other Functions	Notes
AFC()	✅️	⬜️	⬜️
AP()	✅️	✅️	🟩	Issue #47 on 17.15+
APF()	⬜️	✅️	⬜️
AWIPS()	✅️	⬜️	⬜️	Issue #48 on 17.15+
BLE()	✅️	⬜️	⬜️
Client()	✅️	⬜️	⬜️	Issue #28, #29 on 17.15+
Controller()	⬜️	⬜️	🟩
CTS()	⬜️	✅️	⬜️
Dot11()	⬜️	✅️	⬜️
Dot15()	⬜️	✅️	⬜️
Fabric()	⬜️	✅️	⬜️
Flex()	⬜️	✅️	⬜️
General()	✅️	✅️	⬜️
Geolocation()	✅️	⬜️	⬜️
Hyperlocation()	✅️	⬜️	⬜️
LISP()	✅️	⬜️	⬜️
Location()	✅️	✅️	⬜️
Mcast()	✅️	⬜️	⬜️
MDNS()	✅️	⬜️	⬜️
Mesh()	✅️	✅️	⬜️
Mobility()	✅️	⬜️	⬜️
NMSP()	✅️	⬜️	⬜️
Radio()	⬜️	✅️	⬜️
RF()	⬜️	✅️	⬜️
RFTag()	⬜️	⬜️	🟩
RFID()	✅️	✅️	⬜️
Rogue()	✅️	⬜️	⬜️
RRM()	✅️	✅️	⬜️
Site()	✅️	✅️	⬜️
SiteTag()	⬜️	⬜️	🟩
Spaces()	🟨	⬜️	⬜️	Requires 17.15+
URWB()	🟨	🟨	⬜️	Requires 17.18+
WAT()	⬜️	🟨	⬜️	Requires 17.18+
WLAN()	✅️	✅️	⬜️
PolicyTag()	⬜️	⬜️	🟩

[!TIP]

wtpMac is the same as radioMac. WTP (Wireless Termination Point), defined in RFC 5415 denotes an AP.

🔖 Usecases

Runnable examples are available:

List Operation

Usecase 1: List Associating APs

example/list_aps/main.go lists APs managed by the controller.

Click to show example

❯ go run example/list_aps/main.go

Successfully connected! Found 2 APs

AP Name           | MAC Address         | IP Address       | Status
------------------|---------------------|------------------|-----------------
TEST-AP01         | aa:bb:ff:dd:ee:a0   | 192.168.255.11   | registered
TEST-AP02         | aa:bb:ff:dd:ee:b0   | 192.168.255.12   | registered

Usecase 2: List Associating Clients

example/list_clients/main.go lists clients associating to wireless networks.

Click to show example

❯ go run example/list_clients/main.go

Successfully connected! Found 17 clients

MAC Address           | IP Address
----------------------|----------------
08:84:9d:92:47:00     | 192.168.0.84
2a:e3:42:8f:06:c8     | 192.168.0.89
40:23:43:3e:c5:bf     | 192.168.0.62
40:80:e1:6b:11:16     | 192.168.0.92
<snip>

Usecase 3: List WLANs and BSSIDs

example/list_wlans/main.go lists WLANs and their BSSIDs.

Click to show example

❯ go run example/list_wlans/main.go

Successfully connected! Found 7 WLANs across all APs

AP Name           | AP MAC Address    | Slot | WLAN | BSSID             | SSID
------------------|-------------------|------|------|-------------------|-------------------------
TEST-AP01         | aa:bb:ff:dd:ee:a0 |    0 |    1 | aa:bb:ff:dd:ee:a1 | labo-wlan
TEST-AP01         | aa:bb:ff:dd:ee:a0 |    1 |    2 | aa:bb:ff:dd:ee:ad | labo-psk
TEST-AP01         | aa:bb:ff:dd:ee:a0 |    1 |    4 | aa:bb:ff:dd:ee:af | labo-tls
<snip>

Usecase 4: List AP Neighbors

example/list_neighbors/main.go lists neighboring APs detected by the APs.

Click to show example

❯ go run example/list_neighbors/main.go

Successfully connected! Found 11 AP neighbors

AP Name           | Slot | Neighbor BSSID    | Neighbor SSID          | RSSI  | Channel | Last Heard At
------------------|------|-------------------|------------------------|-------|---------|--------------------------
TEST-AP01         |    0 | d8:21:da:a2:30:f0 | Rogue-WiFi             |   -20 |      11 | 2025-09-12 20:24:57
TEST-AP01         |    0 | 08:10:86:bf:07:e3 | rogue-abcdef123-g      |   -62 |       4 | 2025-09-13 06:49:59
TEST-AP01         |    1 | 98:f1:99:c2:03:db | rogue-abcdef123        |   -64 |      36 | 2025-09-13 06:52:57
<snip>

Destructive Operation

Usecase 1: Reload an AP

example/reload_ap/main.go reloads a specified AP by its MAC address.

Click to show example

❯ go run example/reload_ap/main.go

=== Access Point Reload Tool ===
WARNING: This tool will restart access points causing service interruption!
Use only in controlled environments with proper authorization.

Target Controller: wnc1.example.internal
Enter AP MAC address (format: xx:xx:xx:xx:xx:xx or xx-xx-xx-xx-xx-xx): aa:bb:ff:dd:ee:a0
Target AP MAC: aa:bb:ff:dd:ee:a0
This will restart the specified Access Point(s). Type 'YES' to confirm: YES

✓ WNC client created successfully
Executing AP reload for MAC aa:bb:ff:dd:ee:a0
WARNING: AP will become unavailable and disconnect all clients during restart...

✓ AP reload command sent successfully for MAC: aa:bb:ff:dd:ee:a0
Note: AP is now restarting and will be temporarily unavailable
Clients will need to reconnect after AP restart completes

Usecase 2: Reload a Controller

example/reload_controller/main.go reloads the entire wireless controller.

Click to show example

❯ go run ./example/reload_controller/main.go

=== WNC Controller Reload Tool ===
WARNING: This tool will restart the wireless controller!
Use only in controlled environments with proper authorization.

Target Controller: wnc1.example.internal

This will restart the WNC controller. Type 'YES' to confirm: YES

✓ WNC client created successfully
Executing controller reload with reason: Manual reload via CLI tool at 2025-09-06T13:11:50+09:00
WARNING: Controller will become unavailable during restart...

✓ Controller reload command sent successfully
Note: Controller is now restarting and will be temporarily unavailable
Wait for controller to complete restart before attempting reconnection

📦 Used By

• cisco-wnc-exporter - Prometheus exporter for Cisco C9800 Wireless Network Controller metrics (v0.4.2)

🤝 Contributing

Please read the Contribution Guide before submitting PRs and issues and also see the following documents:

• 📋 Make Command Reference — Make targets and the usage
• 📜 Scripts Reference — Per-script usage and sample outputs
• 🧪 Testing Guide — How to run unit and integration tests

🙏 Acknowledgments

I launched this project with the help of GitHub Copilot Coding Agent, and I am grateful to the global developer community for their contributions to open source projects and public repositories.

📄 License

MIT

Documentation

Overview

Package wnc provides a unified Go SDK for the Cisco Catalyst C9800 Wireless LAN Controller RESTCONF API.

This SDK enables developers to communicate with Cisco Catalyst 9800 controllers in an idiomatic, robust, and maintainable way using Go. It provides access to wireless controller configuration, operational data, and management functions through domain-specific service interfaces.

Package wnc provides a unified client for the Cisco Wireless Network Controller API.

Index

• Constants
• Variables
• type APIError
• type Client
  • func NewClient(host, token string, opts ...Option) (*Client, error)
  • func (c *Client) AFC() afc.Service
  • func (c *Client) AP() ap.Service
  • func (c *Client) APF() apf.Service
  • func (c *Client) AWIPS() awips.Service
  • func (c *Client) BLE() ble.Service
  • func (c *Client) CTS() cts.Service
  • func (c *Client) Client() client.Service
  • func (c *Client) Controller() controller.Service
  • func (c *Client) Core() *core.Client
  • func (c *Client) Dot11() dot11.Service
  • func (c *Client) Dot15() dot15.Service
  • func (c *Client) Fabric() fabric.Service
  • func (c *Client) Flex() flex.Service
  • func (c *Client) General() general.Service
  • func (c *Client) Geolocation() geolocation.Service
  • func (c *Client) Hyperlocation() hyperlocation.Service
  • func (c *Client) LISP() lisp.Service
  • func (c *Client) Location() location.Service
  • func (c *Client) MDNS() mdns.Service
  • func (c *Client) Mcast() mcast.Service
  • func (c *Client) Mesh() mesh.Service
  • func (c *Client) Mobility() mobility.Service
  • func (c *Client) NMSP() nmsp.Service
  • func (c *Client) PolicyTag() *wlan.PolicyTagService
  • func (c *Client) RF() rf.Service
  • func (c *Client) RFID() rfid.Service
  • func (c *Client) RFTag() *rf.RFTagService
  • func (c *Client) RRM() rrm.Service
  • func (c *Client) Radio() radio.Service
  • func (c *Client) Rogue() rogue.Service
  • func (c *Client) Site() site.Service
  • func (c *Client) SiteTag() *site.SiteTagService
  • func (c *Client) Spaces() spaces.Service
  • func (c *Client) URWB() urwb.Service
  • func (c *Client) WAT() wat.Service
  • func (c *Client) WLAN() wlan.Service
• type Option
  • func WithInsecureSkipVerify(skip bool) Option
  • func WithLogger(l *slog.Logger) Option
  • func WithTimeout(d time.Duration) Option
  • func WithUserAgent(ua string) Option

Constants

const DefaultTimeout = core.DefaultTimeout

DefaultTimeout is the default request timeout (re-export of core.DefaultTimeout).

Variables

var (
	ErrAuthenticationFailed = core.ErrAuthenticationFailed
	ErrAccessForbidden      = core.ErrAccessForbidden
	ErrResourceNotFound     = core.ErrResourceNotFound
	ErrInvalidConfiguration = core.ErrInvalidConfiguration
	ErrRequestTimeout       = core.ErrRequestTimeout
)

Error sentinels re-exported for consumer side error handling with errors.Is.

Types

type APIError

type APIError = core.APIError

APIError is returned for HTTP error responses (type alias to preserve instanceof semantics with errors.As).

type Client

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

Client represents the unified WNC API client with access to all domain services. This provides a single-import approach to accessing all wireless controller functionality.

func NewClient

func NewClient(host, token string, opts ...Option) (*Client, error)

NewClient creates a new unified WNC client with the specified host, token, and options. This is the main entry point for all wireless controller operations.

func (*Client) AFC

func (c *Client) AFC() afc.Service

AFC returns the Automated Frequency Coordination service.

func (*Client) AP

func (c *Client) AP() ap.Service

AP returns the Access Point service.

func (*Client) APF

func (c *Client) APF() apf.Service

APF returns the Application Policy Framework service.

func (*Client) AWIPS

func (c *Client) AWIPS() awips.Service

AWIPS returns the Advanced Weather Interactive Processing System service.

func (*Client) BLE

func (c *Client) BLE() ble.Service

BLE returns the Bluetooth Low Energy service.

func (*Client) CTS

func (c *Client) CTS() cts.Service

CTS returns the Cisco TrustSec service.

func (*Client) Client

func (c *Client) Client() client.Service

Client returns the wireless client service.

func (*Client) Controller

func (c *Client) Controller() controller.Service

Controller returns the controller management service.

func (*Client) Core

func (c *Client) Core() *core.Client

Core returns the underlying core.Client for advanced use cases. This should typically not be needed for normal usage.

func (*Client) Dot11

func (c *Client) Dot11() dot11.Service

Dot11 returns the 802.11 wireless standard service.

func (*Client) Dot15

func (c *Client) Dot15() dot15.Service

Dot15 returns the 802.15 standard service.

func (*Client) Fabric

func (c *Client) Fabric() fabric.Service

Fabric returns the Fabric service.

func (*Client) Flex

func (c *Client) Flex() flex.Service

Flex returns the FlexConnect service.

func (*Client) General

func (c *Client) General() general.Service

General returns the general controller service.

func (*Client) Geolocation

func (c *Client) Geolocation() geolocation.Service

Geolocation returns the geolocation service.

func (*Client) Hyperlocation

func (c *Client) Hyperlocation() hyperlocation.Service

Hyperlocation returns the hyperlocation service.

func (*Client) LISP

func (c *Client) LISP() lisp.Service

LISP returns the LISP service.

func (*Client) Location

func (c *Client) Location() location.Service

Location returns the location services service.

func (*Client) MDNS

func (c *Client) MDNS() mdns.Service

MDNS returns the multicast DNS service.

func (*Client) Mcast

func (c *Client) Mcast() mcast.Service

Mcast returns the multicast service.

func (*Client) Mesh

func (c *Client) Mesh() mesh.Service

Mesh returns the mesh networking service.

func (*Client) Mobility

func (c *Client) Mobility() mobility.Service

Mobility returns the mobility management service.

func (*Client) NMSP

func (c *Client) NMSP() nmsp.Service

NMSP returns the Network Mobility Services Protocol service.

func (*Client) PolicyTag

func (c *Client) PolicyTag() *wlan.PolicyTagService

PolicyTag returns the Policy Tag service for policy tag management operations. This provides direct access to policy tag CRUD operations without going through WLAN service.

func (*Client) RF

func (c *Client) RF() rf.Service

RF returns the Radio Frequency management service.

func (*Client) RFID

func (c *Client) RFID() rfid.Service

RFID returns the RFID service.

func (*Client) RFTag

func (c *Client) RFTag() *rf.RFTagService

RFTag returns the RF Tag service for RF tag management operations. This provides direct access to RF tag CRUD operations without going through RF service.

func (*Client) RRM

func (c *Client) RRM() rrm.Service

RRM returns the Radio Resource Management service.

func (*Client) Radio

func (c *Client) Radio() radio.Service

Radio returns the radio management service.

func (*Client) Rogue

func (c *Client) Rogue() rogue.Service

Rogue returns the rogue access point detection service.

func (*Client) Site

func (c *Client) Site() site.Service

Site returns the site management service.

func (*Client) SiteTag

func (c *Client) SiteTag() *site.SiteTagService

SiteTag returns the Site Tag service for site tag management operations. This provides direct access to site tag CRUD operations without going through Site service.

func (*Client) Spaces

func (c *Client) Spaces() spaces.Service

Spaces returns the Cisco Spaces integration service. EXPERIMENTAL: Requires IOS-XE 17.15.1+.

func (*Client) URWB

func (c *Client) URWB() urwb.Service

URWB returns the Ultra Reliable Wireless Backhaul service. EXPERIMENTAL: Requires IOS-XE 17.18.1+.

func (*Client) WAT

func (c *Client) WAT() wat.Service

WAT returns the Wireless Application Templates service. EXPERIMENTAL: Requires IOS-XE 17.18.1+.

func (*Client) WLAN

func (c *Client) WLAN() wlan.Service

WLAN returns the WLAN configuration service.

type Option

type Option = core.Option

Option is a functional option for configuring the unified client (re-export of internal core.Option). This allows end users to supply options without importing the internal/core package.

func WithInsecureSkipVerify

func WithInsecureSkipVerify(skip bool) Option

WithInsecureSkipVerify controls TLS certificate verification (lab/testing only).

func WithLogger

func WithLogger(l *slog.Logger) Option

WithLogger sets a custom slog.Logger.

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout sets the request timeout (re-export wrapper).

func WithUserAgent

func WithUserAgent(ua string) Option

WithUserAgent sets a custom User-Agent header value.