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

This SDK requires Go 1.26 or newer.

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.
WithResponseHeaderTimeout(d)	time.Duration	5s	Bounds the wait for response headers.
WithTLSHandshakeTimeout(d)	time.Duration	5s	Bounds the TLS handshake.
WithInsecureSkipVerify(b)	bool	false	Skips TLS verify.
WithProxy(fn)	func(*http.Request) (*url.URL, error)	nil	Sets the proxy resolver; unset means direct.
WithLogger(l)	*slog.Logger	slog.Default()	Sets structured logger.
WithUserAgent(ua)	string	cisco-ios-xe-wireless-go	Custom User-Agent.

Request Options

Every read method takes optional GetOption values after ctx, which apply to that single request. These are a different type from the client Option values above and cannot be mixed.

Option	Value on the wire	Description
WithDefaults(wnc.ReportAll)	with-defaults=report-all	Also returns the leaves in force at their schema default.
WithDefaults(wnc.Explicit)	with-defaults=explicit	Returns the leaves a client set, including any set to their default.
WithFields(expr)	fields=<expr>	Returns only the nodes the expression names.
WithDepth(n)	depth=<n>	Returns only the top n levels of the subtree.

entries, err := client.WLAN().ListWlanCfgEntries(ctx, wnc.WithDefaults(wnc.ReportAll))

[!NOTE]

A plain GET omits every configuration leaf whose value equals its schema default, whoever set it. wnc.Explicit differs: RFC 6243 3.3 requires the server to also return a leaf a client set to that default value. Scope wnc.ReportAll to the container you need: on a whole-container read, the added leaves accumulate across every nested container.

[!NOTE]

A pruned leaf is absent from the answer, and an absent leaf decodes to a zero value, so WithFields and WithDepth should name every node the caller reads: a pruned counter cannot be told from a counter reading zero.

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) GetData(ctx context.Context, path string, opts ...GetOption) ([]byte, error)
  • 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 DefaultsMode
• type GetOption
  • func WithDefaults(mode DefaultsMode) GetOption
  • func WithDepth(levels int) GetOption
  • func WithFields(expression string) GetOption
• type Option
  • func WithInsecureSkipVerify(skip bool) Option
  • func WithLogger(l *slog.Logger) Option
  • func WithProxy(fn func(*http.Request) (*url.URL, error)) Option
  • func WithResponseHeaderTimeout(d time.Duration) Option
  • func WithTLSHandshakeTimeout(d time.Duration) Option
  • func WithTimeout(d time.Duration) Option
  • func WithUserAgent(ua string) Option

Constants

const (
	// ReportAll materializes the leaves in force at their schema default.
	ReportAll = core.DefaultsReportAll
	// Explicit returns the leaves a client set, including any set to their schema default.
	Explicit = core.DefaultsExplicit
)

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 Automated Wireless Intrusion Prevention 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.

Deprecated: the returned type lives in an internal package, so no consumer can name it in a signature or a test double. Use GetData for an untyped read and a service accessor for everything else. Removed in v0.9.0.

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) GetData

func (c *Client) GetData(ctx context.Context, path string, opts ...GetOption) ([]byte, error)

GetData performs a GET on a RESTCONF data path and returns the body as received, for a container this package has no typed accessor for. The path may be given with or without the /restconf/data prefix, and GetOption values apply as they do to a typed read. Errors are the same as everywhere else, *APIError included.

A container or leaf read answers with exactly one top-level key: the module-qualified name of the node requested. A caller decoding the body should check that key rather than trusting its own struct tags, because a tag naming a key the controller does not send decodes to nothing and reports success.

A node the controller carries nothing at answers with no body: the returned slice is non-nil and empty and the error is nil, so check the length before decoding. A path the controller does not have answers 404, which arrives as an *APIError.

The path is sent as given. A caller keying into a list escapes the key value itself; the typed accessors use url.PathEscape, and an unescaped "#" or "?" ends the path early and reads a different node with no error to show for it.

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 DefaultsMode

type DefaultsMode = core.DefaultsMode

DefaultsMode selects the RFC 6243 retrieval mode for WithDefaults.

type GetOption

type GetOption = core.GetOption

GetOption customizes a single GET request (re-export of internal core.GetOption).

func WithDefaults

func WithDefaults(mode DefaultsMode) GetOption

WithDefaults requests the given with-defaults retrieval mode (RFC 8040 4.8.9). Scope it to the container that needs it: on a whole-container read the added leaves accumulate across every nested container.

func WithDepth

func WithDepth(levels int) GetOption

WithDepth limits the answer to an RFC 8040 4.8.2 subtree depth (re-export wrapper). A node the limit cuts is absent exactly as a pruned leaf is, so an absent leaf still decodes to a zero value; bound the depth to what the caller reads.

func WithFields

func WithFields(expression string) GetOption

WithFields limits the answer to an RFC 8040 4.8.3 fields expression (re-export wrapper). A pruned leaf is absent, and an absent leaf decodes to a zero value, so prune only the fields the caller reads.

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 WithProxy

func WithProxy(fn func(*http.Request) (*url.URL, error)) Option

WithProxy routes requests through the proxy the resolver returns (re-export wrapper).

func WithResponseHeaderTimeout

func WithResponseHeaderTimeout(d time.Duration) Option

WithResponseHeaderTimeout bounds the wait for the response headers (re-export wrapper).

func WithTLSHandshakeTimeout

func WithTLSHandshakeTimeout(d time.Duration) Option

WithTLSHandshakeTimeout bounds the TLS handshake (re-export wrapper).

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.