H3Net Protocol Specification

Version: 0.7.8 Date: March 14, 2025

Copyright © 2025 Switchnomix, Inc.. All rights reserved.

Apache 2.0 license

API Specification: h3netschema.json; API

GitHub: H3Net Protocol

Note: This specification is still under development. Schema is updated first and then the specification. Architecture and Operations sections may be behind in terms of update

Table of Contents

  1. Introduction

  2. Design Requirements and Goals

  3. Architecture

  4. Protocol Operations

  5. Message Formats and Definitions

  6. Match-Action Table Structure

  7. Pipeline Processing

  8. Security Considerations

  9. Error Handling and Resilience

  10. Implementation Guidelines

  11. Test Suite

  12. Use Cases and Scenarios

  13. Versioning and Compatibility

  14. References

  15. Glossary

  16. Appendices

1. Introduction

1.1 Overview

The H3Net Protocol is designed to revolutionize network control and security management by enabling enterprises to deploy, manage, and scale their infrastructure effortlessly, without the need for manual coding or extensive staff training. As network and security automation becomes increasingly complex, organizations struggle with fragmented solutions that rely heavily on “glue code” — a costly and maintenance-intensive combination of open-source, commercial, and custom tools. This challenge has persisted for decades, with enterprises repeatedly addressing similar issues using disparate tools and protocols, further exacerbating network and security complexity.

H3Net is dedicated not only to the efficient, secure, and predictive management of today’s networks but also to laying the foundation for the networks of the future. More than just a protocol, H3Net embodies a transformative vision for networking and security, where AI and automation play an increasingly prominent role.

While existing protocols like OpenFlow and P4 have introduced dynamic pipeline capabilities for network infrastructure components such as firewalls, routers, switches, and wireless access points, they are limited in scope and deployment. This creates a need for a unified protocol that can comprehensively manage these diverse dataplanes. H3Net addresses this gap with a standards-based approach built on HTTP/3 and JSON, providing enterprises with seamless, distributed control across a wide range of network devices.

The H3Net Protocol eliminates the dependency on vendor-specific glue code and manual network service provisioning. By offering a vendor-neutral solution, H3Net facilitates centralized management of diverse network devices through a single control plane and unified management console. Devices that natively implement the H3Net Protocol integrate seamlessly into this unified management framework, enabling customers to deploy and manage various network devices without the complexity of vendor-specific configurations. This empowers organizations to leverage the latest advancements in network and security technologies with ease.

How is specification structured?

1.2 Motivation and Need

In today’s complex network environments, enterprises are burdened by vendor lock-in and the extensive effort needed to maintain device-specific glue code for each vendor’s unique API and management protocol. Traditional methods for network and security device management require significant manual intervention, with inconsistent support for modern software-defined and data-driven approaches. Additionally, as enterprises expand their network footprints and adopt multi-vendor infrastructures, the operational costs and complexity multiply, making network and security management a costly, error-prone process.

The H3Net Protocol is designed to address these challenges by providing a unified, vendor-neutral protocol built on modern, web-native standards (HTTP/3 and JSON). H3Net’s approach allows diverse network devices to be managed dynamically and centrally, using a single control plane. By eliminating the need for vendor-specific glue code, H3Net lowers operational costs and reduces complexity, enabling enterprises to achieve rapid deployment, seamless updates, and scalable network management.

REST as an Integration Model

H3Net leverages REST principles not as a traditional API but as an integration model through a shared schema. This approach emphasizes stateful resource interactions over rigid API methods, allowing for a more flexible and dynamic management of network resources. By focusing on a shared integration schema, H3Net enables efficient collaboration between the control plane and network devices, facilitating real-time updates and state synchronization.

REST is best understood as a data-oriented approach where the integration happens through a shared schema (resource model) rather than an explicitly defined API with rigid procedures. A RESTful service exposes a schema (i.e., a representation of resources and their states) rather than defining explicit function calls like an RPC-based API would.

Thus, REST is not about defining function calls (as in an API); rather, it’s about defining stateful resource interactions over HTTP.

Why HTTP/3 over QUIC for H3Net?

HTTP/3 over QUIC, a lightweight and efficient transport layer protocol, provides several advantages that align well with H3Net’s objectives, especially compared to gRPC’s reliance on HTTPS for secure connectivity.

A key benefit of JSON over HTTP/3 is its streamlined connection model. Unlike gRPC, which typically runs over HTTPS to ensure security, HTTP/3 integrates QUIC directly as its transport layer and inherently supports TLS 1.3, eliminating the need for a separate HTTPS layer. This integration simplifies secure connections and may reduce resource consumption, offering a more efficient and effective solution for real-time operations.

While HTTP/3 supports multiplexed streams, it does not natively include gRPC’s persistent, bidirectional streaming model—often used in chat applications that require continuous bidirectional flows. HTTP/3’s unidirectional QUIC streams, while simpler, effectively manage independent data flows with reduced latency.

Though gRPC’s Protocol Buffers are more compact than JSON, HTTP/3 mitigates head-of-line blocking by managing streams independently, helping minimize latency. This makes JSON over HTTP/3 lightweight and practical for dynamic network management, particularly in high-traffic environments. Additionally, HTTP/3’s broad compatibility with the web ecosystem, including native support across browsers and web servers, eases cross-platform deployment and maintenance.

Another major advantage of HTTP/3 over QUIC is its extensive standardization and universal support across platforms and frameworks, unlike gRPC. HTTP/3 is highly compatible with web-based applications, providing reliable connections even in mobile or unstable networks. With QUIC’s built-in features like connection migration and faster recovery from network interruptions, HTTP/3 offers greater resilience than gRPC, which lacks native support for seamless recovery in dynamic network conditions.

Although gRPC includes features like service discovery and client-side load balancing for complex microservices, HTTP/3’s web-first design is often better suited to standard deployment architectures, where HTTP serves as the primary protocol. Its well-established ecosystem and compatibility with most modern browsers and servers make HTTP/3 an ideal choice for H3Net’s cross-platform and multi-vendor support goals.

In environments where scalability, interoperability, and ease of deployment are essential, HTTP/3 over QUIC with JSON provides a secure, lightweight, and reliable solution for H3Net’s real-time, vendor-neutral network management requirements.

For better real-time performance, implementations can utilize WebSockets after establishing the initial HTTP/3 connection. This approach enables higher performance and lower latency, particularly for real-time updates such as telemetry and events.

WebTransport over HTTP/3 QUIC for H3Net

WebTransport is a new protocol that runs over HTTP/3 QUIC, designed for low-latency, bi-directional messaging. It combines the best of:

Key Features:

WebTransport vs. WebSockets
Feature WebSockets WebTransport
Underlying Protocol TCP HTTP/3 (QUIC)
Multiplexing ❌ No (one stream per connection) ✅ Yes (many streams in one connection)
Reliability ✅ TCP ensures delivery ✅/❌ Can be reliable (like TCP) or unreliable (like UDP)
Server Push ❌ No native push ✅ Server can push messages anytime
Latency ⚠️ Higher (TCP-based) ✅ Lower (QUIC-based)

WebTransport is used for real-time updates such as telemetry, events, notifications and controller to device communication.

Where OpenAPI Fits In?

OpenAPI is a service contract definition that specifies how clients can interact with a RESTful (or HTTP-based) service. However, it often inherits an RPC mindset—where the focus is on describing endpoints, operations, and request/response structures, rather than emphasizing the shared schema.

Applying REST principles to Control Planes & Network Devices

In H3Net, the control plane and network devices share an integration schema rather than just an API:

Instead of treating device management as a set of RPC calls (as OpenFlow, gNMI, or SNMP do), H3Net follows a more state-driven model:

This perspective challenges the common “API-first” mindset in network management and instead promotes state-first integration—which aligns more closely with how real-world distributed systems function.

Impact of Artificial Intelligence/Machine Learning (AI/ML) on networks and security

AI/ML models require clean, consistent, and structured data to produce accurate results. Traditional network environments use disparate tools and protocols, leading to fragmented and inconsistent data. Traditional methods often rely on batch processing of logs, which delays anomaly detection and incident response. Manual network optimization is time-consuming and error-prone, especially in dynamic environments. Network security tools often struggle with siloed data and delayed responses to evolving threats. Deploying AI/ML solutions often requires complex integrations with various vendor-specific systems. Many AI/ML models rely on enriched datasets combining multiple data sources, which is often cumbersome in traditional systems. Current network management systems lack the real-time adaptability required for autonomous operation. Traditional methods rely on reactive maintenance, leading to downtime and resource wastage. Managing AI/ML models alongside disparate network management tools increases operational costs and complexity. Enterprises often face barriers to adopting new AI/ML-driven solutions due to legacy systems and vendor lock-in.

Bridging H3Net and Model Context Protocol (MCP) for AI-Driven Insights

The H3Net Protocol’s real-time network and security data capabilities align well with the Model Context Protocol (MCP), which facilitates seamless integration between data sources and AI models such as Claude. By combining H3Net’s efficient data propagation via HTTP/3 + WebTransport with MCP’s structured context management, organizations can build intelligent automation pipelines that leverage real-time network telemetry, security events, and configuration data for AI-driven insights. This integration can enhance use cases such as anomaly detection, predictive maintenance, automated threat response, and dynamic network optimization. H3Net’s ability to deliver enriched, contextual data in real time makes it an ideal data source for MCP-enabled AI models, driving informed decision-making and improved operational efficiency.

GPU/RDMA based AI training/inference in networks

RDMA enables direct memory access from one computer to another without involving the CPU, OS kernel, or interrupts, offering low-latency, high-throughput communication. RDMA NICs, like Mellanox ConnectX or Broadcom adapters, operate using RDMA-capable protocols such as RoCE (RDMA over Converged Ethernet) or iWARP. The Falcon Protocol from Google Cloud is designed to provide a reliable, low-latency hardware transport layer for GPU cluster networks.

H3Net can be extended to support RDMA/RoCEv2/Falcon protocol based networks that are used to build AI training/inference clusters. This is a new use case for H3Net for possible inclusion in future versions of the protocol. One approach is to extend H3Net to include RDMA-specific APIs in the controller to manage devices at the RDMA layer, abstracting these details from higher-level applications. We could also optimize JSON serialization/deserialization or provide an alternative lightweight binary encoding for certain telemetry-intensive RDMA use cases.

+------------------------------------------------------------+
|    H3Net Controller ( Core, Config, Telemetry, Operations )|
|                                                            |
|   - Configuration Management   - Policy Enforcement        |
|   - Telemetry Aggregation      - Flow Rule Updates         |
+------------------------------------------------------------+
    ^            ^               ^               ^
    |            |               |               |
Enrichment   Out-of-band         | H3Net JSON    | RDMA Verbs
                Admin            # over HTTP/3   |  API
                                 |               |
                                 v               v
+------------------------------------------------------------+
|         H3Net Client Dataplane (Device or Software)        |
|(switch, router, wireless AP, firewall, load balancer, PDU )|
|                                                            |
|   - Match-Action Tables       - QoS Rules                  |
|   - Flow Offloading           - Telemetry Collection       |
|   - Device configuration      - Congestion Control         |
|   - RDMA Traffic Management for RDMA-capable NICs          |
+------------------------------------------------------------+
        ^
        |
Out-of-band Admin

Currently, all cloud providers have customized solutions for network and security management of their AI training/inference clusters. This feature is currently out of scope for this version of H3Net.

1.3 Purpose and Scope

The H3Net Protocol offers a unified, scalable solution for managing network Dataplanes across different types of devices, including switches, routers, firewalls, and wireless access points, while removing the need for device-specific glue code. It aims to provide an elastic, secure, and regulatory-compliant control and management plane, enhancing operational agility and reducing costs associated with digital transformation initiatives.

H3Net leverages best practices from existing network management technologies – including OpenFlow for software-defined networking, P4 for programmable Dataplanes, OpenConfig protocols (gNMI, gNOI) for network management and operations, eBPF for packet filtering, and nftables for packet classification and filtering. This protocol specification covers the architecture, message formats, operational guidelines, and security considerations necessary for a comprehensive implementation of the H3Net Protocol.

1.4 Audience

This document is intended for:

This specification provides detailed guidance for both control plane and Dataplane implementation, along with integration guidelines for vendors looking to make their devices H3Net-compatible. It also includes a comparison with related protocols to help readers understand the context and intended purpose of H3Net.

2. Design Requirements and Goals

The H3Net Protocol is designed to address several key challenges in network and security management. This section outlines the essential goals and requirements that guide the protocol’s development.

2.1 Key Challenges Addressed by the H3Net Protocol

2.1.1 Generic Challenges

2.1.2 Vendor-Specific Configuration Issues

Linux-Specific Challenges

Linux serves as the core operating system for most networking and security devices, spanning both commercial and open-source solutions. Vendors typically customize Linux by adding proprietary layers to secure the device and expose specific services. However, this variability introduces challenges that H3Net aims to address by standardizing processes, enhancing interoperability, and reducing the customer burden.

Vendor-Specific Configuration Challenges

2.1.3 Fulfilling the Promise of Software-Defined Networking (SDN)

2.1.4 Role-Based Access to REST APIs

2.1.5 Managing Failover and Conflict Resolution

2.1.6 Asset Management Challenges

2.1.7 Impact of AI/ML

AI/ML is transforming network and security management, enabling new capabilities such as anomaly detection, real-time threat analysis, and automated policy enforcement. There is a need for a standardized, seamless integration of AI/ML models into the control plane, enabling real-time, data-driven decision-making and automation.

By addressing these diverse challenges, H3Net aims to establish a standardized framework that simplifies device management, enhances security, and promotes interoperability. This comprehensive approach reduces complexity, strengthens security measures, mitigates vendor lock-in, and fosters a more adaptable, vendor-neutral ecosystem. H3Net is designed to support the next generation of networks and cybersecurity, incorporating higher speeds, AI/ML, ensuring a secure, efficient, and resilient future in network management and operations.

3. Architecture

The H3Net Protocol’s architecture provides a cohesive framework for managing diverse network and security devices. This design addresses critical requirements such as vendor independence, real-time asset visibility, security, and scalability. It incorporates both control and Dataplanes, with distinct roles and interactions defined between controllers, Dataplanes, and asset management.

3.1 High-Level Architecture

The H3Net Protocol follows a layered design to support flexible interactions across different network devices. The architecture is built on three main components:

This diagram shows the major components of the H3Net Protocol: the Control Plane, Dataplane, and Asset Management Interface.

      +---------------------------+
      |       Control Plane       |
      |---------------------------|
      | - Configuration Manager   |
      | - RBAC and Security       |
      | - Telemetry Collection    |
      | - Conflict Resolution     |
      +---------------------------+
                |
                |
                |
      +---------------------------+
      |       Dataplane          |
      |---------------------------|
      | Device Types:             |
      | - Switches                |
      | - Routers                 |
      | - Firewalls               |
      | - Wireless APs            |
      | - L2 Switch               |
      | - UTM                     |
      | - VoIP (Phone)            |
      | - Load Balancer           |
      | - VPN Gateway             |
      | - Power Dist Unit         |
      |---------------------------|
      | - Packet Processing       |
      | - Telemetry/Monitoring    |
      | - Event Notifications     |
      +---------------------------+
                |
                |
                |
      +---------------------------+
      |   Asset Management        |
      |   (AssetDB Integration)   |
      |---------------------------|
      | - Real-time asset tracking|
      | - Device status updates   |
      | - Lifecycle management    |
      +---------------------------+

3.2 Component Interaction

The components interact through the following core protocols and processes:

3.3 Protocol State Machine

The H3Net Protocol defines several states for communication between the Control Plane and Dataplane:

State transitions are managed through explicit status and response messages, such as ResponseMessage and ErrorMessage, to maintain reliability across the protocol.

This state machine diagram shows the transitions and interactions between states during the lifecycle of the H3Net Protocol communication.

     [Start]
        |
        |
        v
  +----------------------+
  |  Initialization      |
  |----------------------|
  | - Send HelloMessage  |
  +----------------------+
        |
        |
        v
  +-----------------------+
  | Capability Discovery  |
  |-----------------------|
  | - Send CapabilityReq  |
  | - Receive Capabilities|
  +-----------------------+
        |
        |
        v
  +----------------------+
  | Active Configuration |
  |----------------------|
  | - Update Configs     |
  | - Monitor Telemetry  |
  +----------------------+
        |
        |
        v
  +----------------------+
  |   Asset Sync         |
  |----------------------|
  | - Asset Status Update|
  | - Sync with AssetDB  |
  +----------------------+
        |
        |
        v
  +----------------------+
  |  Error Handling      |
  |----------------------|
  | - Error Notifications|
  +----------------------+
        |
        |
        v
     [End]

3.4 Control Plane

The Control Plane serves as the centralized intelligence for managing and configuring network devices. Key roles and functions include:

3.5 Dataplane

The Dataplane represents the network devices that H3Net manages. Key responsibilities include:

3.5.1 Dataplane Pipeline

A dataplane pipeline in networking refers to the series of processing stages that network packets go through as they traverse a network device like a switch or router. Each stage applies specific actions or transformations to the packets based on predefined rules, ensuring efficient and effective packet forwarding, filtering, or modification. The dataplane pipeline is structured into multiple processing stages, each represented as a flow table. These tables define how packets are handled as they traverse the network device.

Flow Tables and Processing Stages:

  1. Flow Tables: Each flow table comprises multiple flow entries, with each entry containing match fields, priority, counters, instructions, and actions. The match fields specify criteria (e.g., specific header values) that incoming packets are compared against. When a packet matches a flow entry, the associated instructions and actions determine its subsequent processing.

  2. Pipeline Processing: Packets enter the first flow table (Table 0) and are evaluated against its flow entries. If a match is found, the specified instructions are executed, which may include modifying the packet, updating its action set, or directing it to another flow table for further processing. This progression continues until the packet reaches the end of the pipeline, where the accumulated action set is executed, typically resulting in forwarding, dropping, or further modification of the packet.

Processing Mechanics:

Efficiency and Flexibility:

This table-based pipeline architecture offers several advantages:

By structuring the dataplane pipeline into flow tables and employing a match-action processing model, a controller can enable efficient, flexible, and programmable network traffic management.

3.6 Protocol Flow Overview

The following sequence diagram illustrates the interactions between the Control Plane, Dataplane, and a network device during the H3Net Protocol operation. This includes the initial connection setup, capability exchange, configuration management, telemetry reporting, network discovery, and health status monitoring.


Control Plane                                      Dataplane
+----------------+                                 +----------------+
|                |                                 |                |
|  Controller    |                                 |  Network Device|
|                |                                 |                |
+----------------+                                 +----------------+
        |                                                  |
        | 1. Hello Message (POST /hello)                   |
        |------------------------------------------------->|
        |                                                  |
        | 2. Hello Response (200 OK)                       |
        |<-------------------------------------------------|
        |                                                  |
        | 3. Capability Request (GET /discovery/capability)|
        |------------------------------------------------->|
        |                                                  |
        | 4. Capability Response (200 OK)                  |
        |<-------------------------------------------------|
        |                                                  |
        | 5. Device Config Update (POST /config/device)    |
        |------------------------------------------------->|
        |                                                  |
        | 6. Config Update Response (200 OK)               |
        |<-------------------------------------------------|
        |                                                  |
        | 7. Pipeline Update (POST /config/pipeline)       |
        |------------------------------------------------->|
        |                                                  |
        | 8. Pipeline Update Response (200 OK)             |
        |<-------------------------------------------------|
        |                                                  |
        | 9. Telemetry Metrics (POST /telemetry/metrics)   |
        |<-------------------------------------------------|
        |                                                  |
        | 10. Telemetry Acknowledgment (200 OK)            |
        |------------------------------------------------->|
        |                                                  |
        | 11. Network Discovery (POST /discovery/network)  |
        |------------------------------------------------->|
        |                                                  |
        | 12. Discovery Response (200 OK)                  |
        |<-------------------------------------------------|
        |                                                  |
        | 13. State Query (POST /operations/state)         |
        |------------------------------------------------->|
        |                                                  |
        | 14. State Query Response (200 OK)                |
        |<-------------------------------------------------|
        |                                                  |
        | 15. Health Status Check (GET /health)            |
        |------------------------------------------------->|
        |<-------------------------------------------------|
        |                                                  |
        | 16. Health Status Response (200 OK)              |
        |<-------------------------------------------------|
        |                                                  |
Key Interactions
  1. Hello Message: Initiates the connection and identifies the device.
  2. Capability Exchange: Determines the device’s capabilities and supported features.
  3. Configuration Management: Updates device settings and pipeline configurations.
  4. Telemetry Reporting: Provides real-time metrics and performance data.
  5. Network Discovery: Identifies network topology and connected devices.
  6. State Query: Retrieves current device state and operational status.
  7. Health Status Check: Monitors the health of the controller and optionally the Dataplane device if supported. This endpoint is publicly accessible, allowing anyone to check the controller’s health status.

3.7 Sequence Diagram Overview

The sequence of interactions is summarized in the following high-level flow:

  1. Device Registration and Capability Exchange:
  2. Configuration Management:
  3. Telemetry and Monitoring:
  4. Asset Management Synchronization:
  5. Pipeline Update and Programming:

This sequence ensures continuous synchronization between the Control and Dataplanes, enabling automated configuration, telemetry monitoring, and asset management updates across the network infrastructure.

3.8 Schema Structure and Extensibility

The H3Net Protocol is defined using OpenAPI 3.0.0 specification format, with a modular structure that supports extensibility and maintainability. The schema is organized into the following key components:

  1. Main Schema File: h3netschema.json serves as the entry point and contains:
  2. Components Section: Located within h3netschema.json under components/schemas, this section defines all data models used throughout the API, including:
3.8.1 Schema Components and Their Purposes

The H3Net Protocol schema is organized into the following key components:

  1. Base Messages and Types: Defined in components/schemas section of the OpenAPI specification, these include:
  2. Configuration Components: Schemas for device configuration:
  3. Pipeline Components: Schemas for dataplane pipeline configuration:
  4. Telemetry Components: Schemas for monitoring and statistics:
  5. Discovery Components: Schemas for capability and network discovery:
  6. Security Components: Schemas for security and access control:

Each component is versioned as part of the overall API version and follows OpenAPI 3.0.0 specification format. The modular structure allows for independent evolution of different functional areas while maintaining backward compatibility.

3.8.2 Extensibility Features

The structured and extensible nature of the H3Net schema ensures it can evolve with the protocol, supporting future enhancements and maintaining compatibility with existing deployments.

3.8.3 H3Net Protocol API Endpoints Summary
Category Endpoint Methods
acl /config/acls GET, POST
/config/acls/device/{deviceId} GET, POST
/config/acls/{aclId} GET, PUT
config /config/acls/{deviceId}/{aclName} GET, PUT, DELETE
/config/acls/{deviceId}/{aclName}/rules POST
/config/acls/{deviceId}/{aclName}/rules/{ruleId} PUT, DELETE
/config/devices GET, POST
/config/devices/info/bulk POST
/config/devices/{deviceId} GET, PUT
/config/devices/{deviceId}/info GET, POST
/config/devices/{deviceId}/interfaces GET
/config/devices/{deviceId}/interfaces/{interfaceId} PUT
/config/devices/{deviceId}/system GET, PUT
/config/routing GET, PUT
/config/switch GET, POST
/config/vlan GET, PUT, POST
core /devices GET, POST
/devices/{deviceId} GET
/events POST
/health GET
/hello POST
discovery /discovery/capabilities GET, POST
/discovery/capabilities/bulk POST
/discovery/network GET, POST
/discovery/network/neighbors/{deviceId} GET
/discovery/network/options GET, PUT
/discovery/network/topology GET
operations /operations/state GET, POST
/operations/state/{deviceId} GET, POST
/operations/state/{deviceId}/interfaces GET
/operations/state/{deviceId}/reboot POST
/operations/state/{deviceId}/tables GET
pipeline /config/pipeline GET, POST
/config/pipeline/flows GET, POST
/config/pipeline/tables GET, POST
/pipeline/flows GET, POST
/tables GET, POST
/tables/{tableId} GET, PUT
/tables/{tableId}/pipeline POST
routing /config/routing/all GET
/config/routing/routes/device/{routeId} GET, PUT, DELETE
/config/routing/{deviceId} GET, PUT
/config/routing/{deviceId}/bgp GET, PUT
/config/routing/{deviceId}/bgp/neighbors GET, POST
/config/routing/{deviceId}/ospf GET, PUT
/config/routing/{deviceId}/static GET, POST
/config/routing/{deviceId}/validate POST
security /security/devices/{deviceId}/roles GET, PUT
/security/roles GET, POST
/security/roles/{roleName} GET, PUT, DELETE
switch /config/switches GET
/config/switches/{deviceId} GET, PUT
/config/switches/{deviceId}/features GET, PUT
/config/switches/{deviceId}/ports GET
/config/switches/{deviceId}/ports/{portId} GET, PUT
telemetry /telemetry/interface_stats POST
/telemetry/meters GET
/telemetry/metrics GET, POST
/telemetry/metrics/bulk POST
/telemetry/metrics/{deviceId} GET
/telemetry/metrics/{deviceId}/environmental GET
/telemetry/metrics/{deviceId}/resources GET
/telemetry/metrics/{deviceId}/thresholds GET, PUT
/telemetry/stats GET
/telemetry/stats/bulk POST
/telemetry/stats/{deviceId} GET
/telemetry/stats/{deviceId}/interfaces GET
/telemetry/stats/{deviceId}/interfaces/{interfaceId}/counters GET, POST, DELETE
/telemetry/stats/{deviceId}/interfaces/{interfaceId}/errors GET
/telemetry/stats/{deviceId}/interfaces/{interfaceId}/qos GET
vlan /config/vlans GET
/config/vlans/id/{vlanId} GET, PUT
/config/vlans/{deviceId} GET, POST
/config/vlans/{deviceId}/{vlanId} GET, PUT, DELETE
/config/vlans/{deviceId}/{vlanId}/ports PUT
/config/vlans/{deviceId}/{vlanId}/properties PUT

3.9 Controller Configuration File

The Controller Configuration File in H3Net is a crucial component that defines the devices under the controller’s management and specifies device-specific configurations such as roles, VLANs, ports, and match actions. This configuration is maintained by the administrator and serves as the basis for the controller’s operations.

3.9.1 Purpose
3.9.2 Configuration Schema

The configuration file can be written in either JSON or YAML. JSON is preferred for programmatic updates, while YAML is more suitable for manual edits by administrators.

Note: This section needs further details about the configuration schema.

Tasks
3.9.2.1 JSON Schema Example
{
  "devices": [
    {
      "device_id": "device-12345",
      "roles": ["core", "config", "telemetry"],
      "default_role": "core",
      "vlans": [
        {
          "vlan_id": 100,
          "name": "Production"
        },
        {
          "vlan_id": 200,
          "name": "Development"
        }
      ],
      "ports": [
        {
          "port_id": 1,
          "description": "Uplink",
          "status": "active"
        },
        {
          "port_id": 2,
          "description": "Server Connection",
          "status": "active"
        }
      ],
      "match_actions": [
        {
          "match": {
            "vlan_id": 100
          },
          "action": "forward_to_port_1"
        }
      ]
    },
    {
      "device_id": "device-67890",
      "roles": ["operations", "security"],
      "default_role": "operations",
      "vlans": [],
      "ports": [],
      "match_actions": []
    }
  ]
}
3.9.2.2 YAML Schema Example
devices:
  - device_id: device-12345
    roles: ["core", "config", "telemetry"]
    default_role: "core"
    vlans:
      - vlan_id: 100
        name: "Production"
      - vlan_id: 200
        name: "Development"
    ports:
      - port_id: 1
        description: "Uplink"
        status: "active"
      - port_id: 2
        description: "Server Connection"
        status: "active"
    match_actions:
      - match:
          vlan_id: 100
        action: "forward_to_port_1"
  - device_id: device-67890
    roles: ["operations", "security"]
    default_role: "operations"
    vlans: []
    ports: []
    match_actions: []
3.9.2.3 Key Elements
3.9.2.4 Usage

This comprehensive configuration schema provides the flexibility needed to manage complex network environments effectively, ensuring the H3Net controller operates with the required clarity and precision.

4. Protocol Operations

The H3Net Protocol defines a set of operations designed to streamline the management, monitoring, and configuration of network devices through structured messages, role-based access, and standardized control methods. Each protocol operation addresses key functionalities within the protocol, allowing the Control Plane and Dataplane to communicate effectively. This section outlines the various operations supported by H3Net, detailing the purpose, message types, and interactions for each.

4.1 Connection Establishment

The Connection Establishment phase initiates communication between a Dataplane device and the Control Plane.

This initial handshake establishes a secure, authenticated channel, where the Dataplane acts as the connection initiator, reducing security risks and protecting sensitive configuration data.

4.2 Capability Exchange

The Capability Exchange phase allows the Control Plane to understand the supported functionalities and configuration capabilities of the Dataplane.

The capability exchange enables the Control Plane to tailor its interactions with the device based on its specific functionalities, ensuring effective and optimized communication without unsupported feature requests.

4.3 Configuration Management

Configuration Management operations allow the Control Plane to apply and retrieve device configurations.

This setup allows for efficient retrieval and management of device configurations in real-time without requiring device reboots.

4.4 Real-Time Updates

Real-time updates are essential for dynamic network management, enabling the Control Plane to adjust settings as needed.

This allows the H3Net Protocol to react to network events or changing conditions by applying changes dynamically, improving flexibility and response times.

4.5 Monitoring and Telemetry

Monitoring and Telemetry operations collect real-time data on the performance and status of the Dataplane devices.

These monitoring and telemetry operations allow the Control Plane to maintain an up-to-date view of the network, enabling proactive management and troubleshooting.

4.6 State Monitoring

State Monitoring is critical for tracking device health and operational status, particularly in distributed networks.

These state queries provide the Control Plane with real-time insights into device conditions and can be used to identify or troubleshoot network issues effectively.

4.7 Event Notifications

Event Notifications provide the Control Plane with immediate updates on significant changes or issues within the network.

Event notifications allow the Control Plane to respond quickly to changes in network status, facilitating prompt remediation or reconfiguration if necessary.

4.8 Error Handling

Error Handling ensures robust and reliable communication, managing issues that arise during configuration or operational processes.

By providing detailed error messages, H3Net supports efficient troubleshooting and minimizes downtime due to configuration errors or unexpected device conditions.

Each protocol operation outlined here ensures that the H3Net Protocol can comprehensively manage network devices, support dynamic configurations, monitor health, and maintain secure, reliable communication across distributed network environments.

4.9 Core API Endpoints

The H3Net Protocol defines several core API endpoints that implement the protocol operations. These endpoints are organized by functional area and follow RESTful principles. The key endpoints include:

  1. Connection Management
  2. Device Management
  3. Capability Discovery
  4. Network Discovery
  5. Configuration Management
  6. Telemetry and Monitoring
  7. State Operations
  8. Security and RBAC
  9. Event Notifications

These endpoints form the core of the H3Net Protocol’s RESTful API and implement the operations described in previous sections. Each endpoint follows consistent patterns for request and response handling, error reporting, and authentication.

5. Message Formats and Definitions

The H3Net Protocol relies on a structured set of message types defined in JSON to manage interactions between the Control and Dataplanes. These messages enable flexible configuration, monitoring, telemetry, and event handling across a diverse range of network devices. This section details the message formats, the JSON schema definitions for each, and the differences between key configuration messages. The main message categories include:

5.1 Message Type Overview

H3Net Protocol messages are categorized based on their purpose and function. The main types of messages include:

These message types are built with a consistent structure to ensure interoperability and efficient parsing by both the Control and Dataplanes.

5.2 JSON Schema for Messages

The H3Net Protocol defines a comprehensive JSON schema for all message types. These schemas are defined in the components/schemas section of the OpenAPI specification and include:

  1. Base Message Types
  2. Connection Messages
  3. Capability Messages
  4. Configuration Messages
  5. Pipeline Messages
  6. Telemetry Messages
  7. State Messages
  8. Event Messages
  9. Security Messages

Each message schema defines the structure, required fields, data types, and validation rules for the corresponding message type. The schemas use JSON Schema features like $ref for referencing common definitions, allOf for inheritance, and validation keywords like required, enum, and pattern.

The complete schema definitions can be found in the h3netschema.json file and its referenced component files.

5.3 New Message Types

New message types may be introduced as the protocol evolves. These would be added under well-defined categories to maintain consistency. Examples of potential new message types include:

New messages would follow the protocol’s standard JSON schema format and would require updates to both the schema and validation logic in implementations.

5.4 Message Initiators

The H3Net Protocol specifies which plane (Control or Data) initiates each message, helping define the protocol flow:

By specifying initiators, the protocol flow remains predictable, and roles are clearly defined, reducing the risk of miscommunication between planes.

5.4.1 Bidirectional Message Handling in H3Net Protocol
5.4.1.1 Challenge: Handling Response Messages in WebTransport

The H3Net Protocol leverages WebTransport as its underlying transport mechanism, providing bidirectional communication between clients and servers. While the OpenAPI schema effectively defines client-initiated requests and their expected responses, it does not inherently address server-side handling of client-generated response messages.

This presents a unique challenge in the H3Net Protocol implementation: how to consistently handle response messages (like CAPABILITY_QUERY_RESPONSE) that are sent from clients to servers but don’t have corresponding API endpoints defined in the schema. These messages are part of the bidirectional flow but lack explicit operation mappings in the generated server code.

Traditional REST APIs typically follow a request-response pattern where the client initiates a request and the server responds. However, in the H3Net Protocol’s bidirectional communication model, both clients and servers can initiate messages, and both must handle responses. This bidirectional nature requires a more sophisticated approach to message handling.

5.4.1.2 Solution: Message Handler Registry Pattern

To address this challenge, the H3Net Protocol implementation adopts a pattern inspired by WebSocket implementations: the Message Handler Registry Pattern. This approach provides several key benefits:

  1. Decoupling of Message Handling Logic: By separating the message handling logic from the operation mapping logic, the implementation becomes more maintainable and extensible.

  2. Consistent Response Processing: All response messages are handled in a consistent way, regardless of whether they have corresponding operations in the schema.

  3. Extensibility: New message types can be added without modifying the core message handling logic, making the protocol more adaptable to future requirements.

  4. Improved Error Handling: Dedicated handlers for specific message types can implement custom error handling logic appropriate for each message type.

  5. Enhanced Logging and Monitoring: Message-specific handlers can provide detailed logging and monitoring for each message type, improving observability.

The implementation consists of the following components:

  1. Message Handler Type: A function type that defines the signature for message handlers.

    type MessageHandler func(session *webtransport.Session, payload interface{}) error

  2. Message Handler Registry: A map that associates message types with their handler functions.

    messageHandlers map[string]MessageHandler

  3. Handler Registration: A method to register handlers for specific message types.

    func (h *WebTransportHandler) RegisterMessageHandler(messageType string, handler MessageHandler)

  4. Message Dispatch: Logic to dispatch incoming messages to their registered handlers or fall back to the operation mapping approach.

5.4.1.3 Implementation Example: Handling CAPABILITY_QUERY_RESPONSE

The CAPABILITY_QUERY_RESPONSE message serves as an illustrative example of this pattern. When a client responds to a CAPABILITY_REQUEST with its capabilities, the server needs to process this response despite the absence of a corresponding API endpoint in the schema.

Using the Message Handler Registry Pattern, the server registers a dedicated handler for CAPABILITY_QUERY_RESPONSE messages:

handler.RegisterMessageHandler("CAPABILITY_QUERY_RESPONSE", handler.handleCapabilityQueryResponse)

The dedicated handler extracts the device information and capabilities, logs them for debugging purposes, and sends a confirmation response back to the client:

func (h *WebTransportHandler) handleCapabilityQueryResponse(session *webtransport.Session, payload interface{}) error {
    // Extract device info
    deviceId := extractDeviceId(payload)
    
    // Process capabilities
    capabilities := extractCapabilities(payload)
    
    // Log capabilities for debugging
    logCapabilities(deviceId, capabilities)
    
    // Send confirmation response
    return h.sendMessage(session, createCapabilitiesProcessedResponse(deviceId))
}
5.4.1.4 Benefits for H3Net Protocol Implementations

This approach provides several benefits for H3Net Protocol implementations:

  1. Improved Code Organization: Message handling logic is organized by message type, making the code easier to understand and maintain.

  2. Reduced Complexity: The main message handling function becomes simpler, as it delegates to specific handlers for each message type.

  3. Better Testability: Message handlers can be tested in isolation, making it easier to ensure they work correctly.

  4. Enhanced Extensibility: New message types can be added by simply registering new handlers, without modifying existing code.

  5. Consistent Error Handling: Each message type can have its own error handling logic, appropriate for its specific requirements.

By adopting this pattern, the H3Net Protocol implementation provides a robust and maintainable way to handle bidirectional communication, ensuring that all messages are processed consistently regardless of their origin or destination.

5.5 DeviceConfigUpdate vs. PipelineUpdate

The H3Net Protocol distinguishes between DeviceConfigUpdateMessage and PipelineUpdateMessage to separate general device configurations from specific packet processing rule updates.

This separation enables the protocol to handle broad device configurations and packet-specific rules independently, ensuring that device configuration changes don’t interfere with real-time packet processing requirements.

This structured approach to message formats, initiators, and configuration updates ensures that the H3Net Protocol remains flexible, scalable, and secure across a diverse range of network devices.

6. Match-Action Table Structure

The H3Net Protocol uses a match-action table structure to enable programmable packet processing pipelines on the Dataplane. This structure allows network devices to apply specific rules to incoming packets based on defined matches and associated actions. The tables are flexible, supporting both standard predefined structures and custom tables that can be adapted to particular use cases or network requirements.

6.1 Standard Tables

Standard tables provide a set of commonly used match-action structures applicable across various network devices. These tables are defined within the H3Net schema to ensure consistency and interoperability between devices, enabling a unified management approach. Examples of standard tables include:

These tables provide the basic functionality for handling common network requirements, including security filtering, VLAN management, and Layer 2/3 forwarding. By standardizing these tables, the protocol ensures efficient processing and consistency across devices.

6.2 Custom Tables

Custom tables allow network administrators to define and deploy specialized match-action rules tailored to specific network or application needs. The H3Net schema supports these custom tables, giving administrators flexibility while still adhering to a structured, manageable framework.

The flexibility of custom tables allows the H3Net Protocol to accommodate diverse network environments and use cases, while maintaining a cohesive management framework.

7. Pipeline Processing

Pipeline processing in the H3Net Protocol refers to the sequence of operations applied to packets as they traverse the device. This is managed through match-action tables that determine the processing steps based on packet characteristics and predefined rules.

7.1 Pipeline Configuration

Pipeline configuration sets the initial structure and order of match-action tables that packets will encounter as they are processed by the device. This configuration is critical to ensuring that packet handling aligns with network policies and operational goals.

The pipeline configuration provides a foundation for the packet processing rules, ensuring that all packets are handled efficiently and in alignment with network policies.

7.2 Pipeline Update Mechanism

The pipeline update mechanism allows dynamic changes to the packet processing rules within an existing pipeline configuration. This mechanism enables real-time updates to the match-action tables without requiring a full device reconfiguration.

The pipeline update mechanism provides a powerful tool for maintaining an adaptive, policy-driven network that can react quickly to operational needs while avoiding downtime or configuration conflicts.

These sections provide an overview of how the H3Net Protocol structures its match-action tables and manages pipeline processing, enabling efficient, flexible packet handling across diverse network environments.

8. Security Considerations

Security is a central concern for the H3Net Protocol, particularly given its role in managing network configurations, real-time monitoring, and device interactions. This section outlines the security measures necessary to ensure data integrity, prevent unauthorized access, and enable a secure, resilient network environment.

8.1 Threat Model

The H3Net Protocol threat model considers various potential attacks and security risks that may compromise the integrity or confidentiality of the network. Key threats include:

The H3Net Protocol mitigates these threats by incorporating role-based access, secure communication channels, and rigorous authentication methods.

To address the authentication support in the H3Net Specification while considering the current and future direction, the following approach can be used:

8.2 Authentication Support Overview

The H3Net Specification provides several authentication mechanisms to ensure secure communication between the dataplane and the controller. While multiple schemes are currently supported, the long-term goal is to transition towards exclusive certificate-based authentication. This approach offers enhanced security by leveraging cryptographic certificates for identity verification and data integrity.

The H3Net Protocol supports the following authentication schemes:

  1. API Key Authentication:
  2. Bearer Token Authentication:
  3. OAuth2 Authentication:
  4. Certificate-Based Authentication (Preferred):

H3Net supports only client-initiated authentication, with the controller always operating in server mode. This design is crucial for production deployments, as it eliminates the need for IT operations to open internal firewall ports, allowing the controller to connect securely to each dataplane without additional network configuration.

8.2.1 Current Authentication Schemes

The schema defines various authentication methods, including API key and Bearer token mechanisms. These schemes are categorized based on their application within different roles in the H3Net ecosystem:

8.2.2 Transition to Certificate-Based Authentication

To enhance security and streamline authentication processes, the H3Net Specification will eventually support only certificate-based authentication. This method provides robust security by using digital certificates for mutual authentication, ensuring both the controller and dataplane can securely identify each other.

Devices can operate in one of two modes for certificate authentication:

In all configurations, device dataplane acts in the “client” mode, while the controller operates in the “server” mode.

8.2.3 Deprecation Notice

While the current authentication schemes provide necessary functionality, they are marked for deprecation as the specification progresses towards the exclusive use of certificate-based methods. Stakeholders should plan for a phased migration to ensure a smooth transition without impacting operations.

8.2.4 Encryption and Authentication

The H3Net Protocol requires robust encryption and authentication mechanisms to ensure secure communication and protect data integrity.

These encryption and authentication standards reduce the risk of unauthorized access and interception, making H3Net communication resilient against external threats.

8.2.5 Best Practices

This approach ensures that the H3Net Specification remains flexible, secure, and future-proof, accommodating current needs while planning for long-term security enhancements.

8.3 Role-Based Access Control (RBAC)

H3Net Protocol implements Role-Based Access Control (RBAC) to enforce fine-grained permissions, limiting users and devices to specific APIs and operations. RBAC supports scalability by allowing for custom roles, each with unique access levels, preventing unauthorized access to critical configuration and telemetry data.

8.3.1 Types of Controllers

Controllers in H3Net Protocol are categorized by function and level of access, ensuring that roles align with the controller’s purpose:

Controller roles define the specific functionalities available to the dataplane, primarily for security purposes, while also optimizing functionality. By isolating functionalities, these controller types reduce the risk of excessive permissions and enforce the principle of least privilege. Additionally, these controllers seamlessly integrate with various applications and data sources to enhance their capabilities. For example, a telemetry controller might feed data into a real-time analytics platform like Prometheus, while a core controller could integrate with a DHCP server to dynamically manage network leases. This northbound integration is built directly into the controller, enabling efficient and secure network management.

8.3.2 Controller and Device Roles

Each controller and device role defines specific permissions, ensuring that only authorized entities can perform certain actions:

Role assignment and permission restrictions prevent unauthorized actions, creating a more secure, managed environment for network operations.

8.3.3 Controller Operation and Role Management
Controller Configuration

The H3Net Controller operates based on a configuration file provided by the administrator. This configuration file contains a list of devices that the controller is responsible for managing. Each device entry includes:

Handling RoleUpdateMessage

When a device sends a RoleUpdateMessage to the controller, the following steps occur:

  1. Role Verification: The controller checks the role against the enumerated list of roles in the configuration file for that specific device.
  2. Role Mapping: If the role is valid, the controller maps the role to the device and updates its operational state accordingly.
  3. Default Role Assignment: If the role is not recognized or missing, the controller assigns the default role specified in the configuration file to ensure consistent and predictable behavior.
Problem and Solution

The primary challenge is ensuring the controller correctly maps roles to devices, especially in dynamic environments. The enumerated list of roles and the mandatory default role provide a structured way to handle this complexity, ensuring the controller always knows how to manage each device.

Configuration File Example
{
  "devices": [
    {
      "device_id": "device-12345",
      "roles": ["core", "config", "telemetry"],
      "default_role": "core"
    },
    {
      "device_id": "device-67890",
      "roles": ["operations", "security"],
      "default_role": "operations"
    }
  ]
}
8.3.4 Certificate Authentication

Certificate-based mutual authentication is employed for secure communication between Control and Dataplanes:

Certificate authentication strengthens security by verifying identities and ensuring only trusted entities communicate over the H3Net Protocol.

8.3.5 API Catalog and Roles

API catalogs define which APIs are accessible by specific roles. For example:

Each catalog enforces strict access control, reducing the risk of unauthorized access to sensitive network management functions.

8.4 Best Practices for Secure Implementation

To ensure the secure implementation of the H3Net Protocol, the following best practices are recommended:

8.4.1 Security Schemes in OpenAPI Specification

The H3Net Protocol defines several security schemes in the OpenAPI specification (h3netschema.json) to enforce authentication and authorization:

  1. Role-Based API Keys:
  2. OAuth2 Authentication:
  3. Legacy Authentication Methods (to be deprecated):

Each API endpoint in the H3Net Protocol specifies which security schemes are required for access, ensuring that only properly authenticated and authorized clients can interact with the endpoints. The security schemes align with the RBAC model, enforcing the principle of least privilege by restricting access based on the client’s assigned role.

By following these practices, organizations can ensure that the H3Net Protocol operates securely, minimizing risk and supporting robust network management capabilities.

9. Error Handling and Resilience

Error handling and resilience are crucial for the stability and reliability of the H3Net Protocol. Effective error handling ensures smooth operations, minimizes downtime, and facilitates quick recovery from failures. This section provides guidelines for error management, failover processes, and conformance requirements to maintain protocol reliability and fault tolerance across diverse network environments.

9.1 Error Handling Guidelines

Error handling in the H3Net Protocol is designed to manage expected and unexpected issues that may arise during device configuration, telemetry, and pipeline updates. H3Net defines specific error responses for different failure scenarios:

Error handling in the H3Net Protocol emphasizes clarity, consistency, and fault isolation, allowing errors to be quickly identified, communicated, and addressed.

HTTP Status Error Type Typical Causes
400 Data Validation Failed Invalid input format/values
401 User Not Authenticated Missing/invalid authentication credentials
403 Permission Check Failed Role lacks required permissions
404 Resource Not Found Requested device/configuration missing
409 Business Rule Conflict Conflicting configuration rules
415 Unsupported Data Format Invalid Content-Type header
500 Internal Server Error Unexpected system failure

All errors follow the standard error format:

{
  "errorCode": "H3NET-403",
  "errorMessage": "Insufficient permissions for requested operation",
  "timestamp": "2025-02-08T12:34:56Z",
  "details": {
    "required_role": "NetworkAdmin",
    "attempted_operation": "/config/switches/switch-01"
  }
}

9.2 Failover and Conflict Resolution

Resilience in the H3Net Protocol is achieved through advanced failover mechanisms and conflict resolution strategies, ensuring uninterrupted operations even during controller or network failures.

The failover and conflict resolution mechanisms in H3Net are crucial for sustaining protocol resilience. They enable the system to handle both planned and unexpected disruptions gracefully, ensuring continuous operation without compromising security or stability.

9.3 Conformance Requirements

Conformance requirements establish the baseline functionality that must be supported by all H3Net-compliant devices and controllers to ensure interoperability and protocol fidelity.

These conformance requirements establish a standard level of functionality across all H3Net deployments, ensuring that devices and controllers interact consistently and predictably within the protocol ecosystem.

The H3Net Protocol’s error handling, resilience, and conformance standards are designed to maintain high availability, enable rapid recovery, and ensure compliance across all network components. This approach provides a strong foundation for reliable, secure, and standardized network management.

10. Implementation Guidelines

The H3Net Protocol offers a flexible yet standardized approach for implementing network control and Dataplanes. These guidelines provide developers and network engineers with recommendations for effective implementation, focusing on protocol compatibility, scalability, and security.

10.1 Control Plane Implementation

The Control Plane serves as the command center for managing, configuring, and monitoring Dataplane devices. Effective implementation of the Control Plane includes:

These guidelines ensure that the Control Plane can manage diverse devices securely and efficiently while providing redundancy for high availability.

10.2 Dataplane Implementation

The Dataplane is responsible for packet processing, telemetry reporting, and responding to configuration commands from the Control Plane. To implement a robust Dataplane:

These guidelines ensure that the Dataplane remains responsive, secure, and aligned with H3Net’s protocol standards.

10.3 Vendor Integration Guidelines

Integrating the H3Net Protocol with vendor-specific devices requires adapting the protocol’s standard messages and functions to each device’s unique APIs, firmware, and hardware capabilities.

These integration guidelines facilitate smooth operation across multiple vendors while maintaining the consistency and interoperability of the H3Net Protocol.

10.4 NAPALM-like Integration

NAPALM (Network Automation and Programmability Abstraction Layer with Multivendor support) provides a framework for interacting with network devices through a unified API. While NAPALM is a powerful community driven open source tool for network automation, its limitations — ranging from partial vendor support, lack of real-time event-driven automation, limited device/network services support and inconsistent feature implementation to scalability and security concerns — highlight the need for careful evaluation and supplemental strategies when deploying it in complex or large-scale environments. A NAPALM-like integration for H3Net which addresses these limitations can further streamline multi-vendor support and enable flexible, extensible management.

By adopting NAPALM-like integration techniques, H3Net achieves a high degree of flexibility, multi-vendor compatibility, and streamlined management, enabling more efficient automation across heterogeneous network environments.

These implementation guidelines for the Control Plane, Dataplane, vendor-specific integration, and NAPALM-like compatibility ensure that the H3Net Protocol operates smoothly across diverse network infrastructures, enabling reliable, scalable, and secure network management.

11. Test Suite

To enable testing of dataplane implementations, a test suite is provided that can be used to verify the implementation of the H3Net Protocol. The test suite is expected to be written in Go language and will be available in the H3Net repository.

12. Use Cases and Scenarios

The H3Net Protocol is designed to handle diverse network management and configuration scenarios, from routine network configurations to advanced pipeline management and telemetry monitoring. This section explores common use cases to demonstrate the protocol’s flexibility and capabilities across various network environments.

12.1 Common Network Configurations

The H3Net Protocol simplifies and standardizes network configuration management, allowing administrators to handle device configurations in a consistent, centralized way.

These common network configurations demonstrate H3Net’s ability to streamline and unify management tasks across diverse devices.

12.2 Pipeline Management

Pipeline management is central to controlling packet processing behavior within the Dataplane. The H3Net Protocol’s match-action tables allow administrators to define and manage the packet processing pipeline in a flexible, vendor-neutral way.

Pipeline management with H3Net provides the flexibility needed for efficient, secure, and high-performance network traffic handling in real-time.

12.3 Telemetry Scenarios

H3Net’s telemetry capabilities support continuous monitoring of network performance and health, providing insights for proactive management and rapid response to issues.

H3Net’s telemetry capabilities offer extensive monitoring and alerting options, enabling proactive network management and optimized resource utilization.

12.4 AI/ML Integration

H3Net empowers AI/ML pipelines by providing direct access to its telemetry messages and state query responses, enabling seamless integration for training, analysis, and prediction. Real-time streaming telemetry allows AI models to monitor live network metrics, detect anomalies as they occur, and proactively address potential issues. By analyzing dynamic pipeline updates, AI systems can predict configuration problems or performance bottlenecks and suggest optimizations, such as traffic re-routing, load balancing, or QoS adjustments. H3Net’s telemetry and state data also allow AI models to evaluate the impact of changes before implementing them, ensuring informed decision-making.

In the realm of security, AI/ML models can leverage H3Net’s firewall and ACL configurations, combined with real-time state data, to predict and prevent security breaches. Dynamic rule updates via H3Net enable instant enforcement of security policies, allowing networks to adapt to evolving threats in real-time.

H3Net’s unified, vendor-neutral protocol eliminates integration challenges, simplifying the deployment of AI-driven solutions across multi-vendor environments. Its integration with asset management systems and other enterprise tools enriches contextual data about devices, locations, and configurations, feeding advanced AI models for predictive maintenance, capacity planning, and compliance auditing.

By enabling closed-loop automation, H3Net allows AI models to detect, decide, and act in real time through its robust control plane. This capability includes dynamically configuring pipelines, modifying routing, and enforcing security policies autonomously. AI systems can analyze telemetry data to identify patterns of hardware degradation or performance issues, generating predictive alerts for proactive maintenance and optimal resource utilization.

H3Net reduces operational overhead by unifying network management, enabling AI/ML systems to interact with a single protocol for diverse devices. This unified approach enhances ROI for AI/ML initiatives by streamlining their integration into network management workflows. H3Net’s open-source nature and standardized schema accelerate AI/ML adoption, empowering network teams to experiment with cutting-edge algorithms without overhauling existing infrastructure.

These use cases highlight the versatility of the H3Net Protocol in addressing common and advanced network management scenarios, demonstrating its ability to handle complex configurations, flexible pipeline management, and robust telemetry monitoring.

13. Versioning and Compatibility

Handling protocol and schema versioning is essential for ensuring compatibility and smooth operation as the H3Net Protocol evolves. Since the dataplane client initiates the connection to the controller, a clear strategy for managing versioning is vital to accommodate potential differences between dataplane and controller software versions. Effective versioning and compatibility management ensure H3Net Protocol deployments can evolve without disrupting existing network operations or breaking interoperability between control and dataplanes. This section outlines the versioning conventions and compatibility practices necessary for robust protocol management.

13.1 Protocol Versioning Strategy

Example HTTP/3 Request Header
POST /control HTTP/3
Host: controller.company.com
H3Net-Protocol-Version: 1.0
Content-Type: application/json
Example HTTP/3 Response Header
HTTP/3 200 OK
Content-Type: application/json
H3Net-Protocol-Version: 1.0

13.2 Compatibility Checks

13.3 Example Version Negotiation Workflow

  1. Dataplane sends a connection request with H3Net-Protocol-Version: 1.0.
  2. Controller responds with H3Net-Protocol-Version: 1.1 (if backward-compatible) or 400 Bad Request with a list of supported versions if not.

13.4 Schema Versioning Strategy

Example JSON Configuration
{
    "schema_version": "1.0",
    "match_action_tables": [
        {
            "table_name": "vlan",
            "entries": [
                {"match": {"vlan_id": 100}, "action": "forward_to_port_1"}
            ]
        }
    ]
}

13.5 Backward and Forward Compatibility

13.6 Schema Evolution

13.7 Additional Versioning Practices

The versioning and compatibility practices for H3Net Protocol provide a robust framework for iterative improvements while ensuring operational continuity across protocol versions.

14. References

This section provides key references for understanding the standards, related technologies, and foundational resources relevant to the H3Net Protocol.

14.1 RFCs

  1. RFC 2616: Hypertext Transfer Protocol – HTTP/1.1
  2. RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2
  3. RFC 7540: Hypertext Transfer Protocol Version 2 (HTTP/2)
  4. RFC 8446: The Transport Layer Security (TLS) Protocol Version 1.3
  5. RFC 9000: QUIC: A UDP-Based Multiplexed and Secure Transport

These RFCs provide foundational information on HTTP and TLS, which are integral to the H3Net Protocol’s communication and security architecture.

  1. OpenFlow: A protocol standard for SDN, allowing dynamic control over network traffic through programmable rules.
  2. P4: A programming language for defining packet-processing behavior, enabling flexible, programmable Dataplanes.
  3. OpenConfig (gNMI, gNOI): Protocols and models for network management and telemetry, often used in SDN environments.
  4. eBPF: A technology for efficient, in-kernel packet filtering and manipulation, commonly used for monitoring and security.
  5. nftables: A packet classification framework in Linux that provides advanced firewall and traffic control capabilities.

These related technologies provide context for the H3Net Protocol’s objectives and design principles, offering complementary and alternative solutions for network management.

15. Glossary

This glossary provides definitions for key terms and concepts within the H3Net Protocol, aiding in clarity and understanding for implementers and network operators.

16. Appendices

The appendices provide supplementary information to support the H3Net Protocol specification, including visual representations of architecture and flow through ASCII diagrams and example configurations for practical implementation.

16.1 ASCII Diagrams

The following ASCII diagrams illustrate the high-level architecture, protocol flow, and state machine for the H3Net Protocol, offering a visual overview of interactions between the Control and Dataplanes and various protocol components.

  1. High-Level Architecture

    +---------------------------+
|        Control Plane      |
|                           |
| +-----------------------+ |
| |   Core Controller     | |
| |-----------------------| |
| | Config Controller     | |
| | Telemetry Controller  | |
| | Operations Controller | |
| +-----------------------+ |
+---------------------------+
             |
             |
             | HTTP/3 with JSON
             v
+---------------------------+
|         Dataplane        |
|                           |
| +-----------------------+ |
| |     Device Roles      | |
| |  - Switch             | |
| |  - L2 Switch          | |
| |  - Router             | |
| |  - Firewall           | |
| |  - UTM                | |
| |  - Wireless AP        | |
| |  - VoIP (Phone)       | |
| |  - Load Balancer      | |
| |  - VPN Gateway        | |
| |  - Power Dist Unit    | |
| +-----------------------+ |
|                           |
+---------------------------+

  2. Protocol Flow Overview

    +-----------------------------+
|        Control Plane        |
+-----------------------------+
|                             |
|   1. Initiate HelloMessage  |
|---------------------------->|
|                             |
|   2. CapabilityExchange     |
|<----------------------------|
|                             |
|   3. ConfigUpdate           |
|---------------------------->|
|                             |
|   4. Telemetry Request      |
|---------------------------->|
|                             |
|   5. Error Handling         |
|<----------------------------|
|                             |
+-----------------------------+

  3. Protocol State Machine

    +-------------------------+
|       INIT STATE        |
+-------------------------+
             |
             | HelloMessage
             v
+-------------------------+
|    CAPABILITY EXCHANGE  |
+-------------------------+
             |
             | CapabilityResponse
             v
+-------------------------+
|       ACTIVE STATE      |
+-------------------------+
             |
             | Config/Telemetry
             |
+-------------------------+
|       ERROR STATE       |
+-------------------------+

These diagrams outline the primary components and flow, helping users visualize how the protocol operates in both routine and error scenarios.

15.2 Example Configurations

Example configurations provide sample JSON messages and configurations to demonstrate practical H3Net Protocol use cases. These examples cover standard configurations, telemetry settings, and error handling for easy reference.

  1. Example Configuration for VLAN Assignment

    {
  "type": "DeviceConfigUpdateMessage",
  "timestamp": "2024-01-15T12:34:56Z",
  "deviceId": "switch-01",
  "config": {
    "vlan": {
      "id": 10,
      "name": "Sales VLAN",
      "untaggedPorts": [1, 2, 3],
      "taggedPorts": [10, 11]
    }
  }
}

    This message assigns VLAN 10 to ports on a switch, marking certain ports as untagged for VLAN traffic and others as tagged.

  2. Example Telemetry Request

    {
  "type": "TelemetryMessage",
  "timestamp": "2024-01-15T13:45:00Z",
  "deviceId": "router-01",
  "metrics": {
    "interfaceStats": true,
    "cpuUsage": true,
    "memoryUsage": true
  }
}

    This telemetry message requests interface statistics, CPU usage, and memory usage data for real-time monitoring.

  3. Error Handling Example

    {
  "type": "ErrorMessage",
  "timestamp": "2024-01-15T14:55:00Z",
  "errorCode": 403,
  "errorMessage": "Access Denied",
  "context": "Unauthorized access to Config Controller",
  "causes": [
    "Invalid permissions for API call",
    "Role mismatch for attempted configuration"
  ]
}

    This example illustrates an error message indicating access denial, including context and possible causes for diagnostic purposes.

  4. Example Configuration for Role-Based Access

    {
  "type": "RoleUpdateMessage",
  "timestamp": "2024-01-15T15:10:00Z",
  "deviceId": "firewall-02",
  "role": "Telemetry Controller",
  "permissions": ["GET /telemetry/*", "POST /eventNotification"]
}

    This role update message assigns specific telemetry-related permissions to a controller interacting with a firewall device.

  5. Pipeline Update Example for Traffic Filtering

    {
  "type": "PipelineUpdateMessage",
  "timestamp": "2024-01-15T16:00:00Z",
  "deviceId": "switch-02",
  "tableName": "Port ACL Table",
  "flowEntry": {
    "priority": 100,
    "match": {
      "ipSrc": "192.168.1.0/24",
      "ipDst": "10.0.0.0/24",
      "protocol": "TCP"
    },
    "action": "drop"
  }
}

    This configuration updates the pipeline to drop TCP traffic between specific IP ranges, enforcing security policies at the switch level.

These examples provide practical reference points for implementing and troubleshooting H3Net Protocol configurations across various network devices and scenarios. They demonstrate how to configure devices, manage telemetry, handle errors, and apply access controls, all while adhering to the H3Net specification.