HiCAIN Control Plane Reference¶

This document is the complete reference for managing the HiCAIN Virtual Switch. It covers the three management interfaces, the JSON Management Socket API (the authoritative interface), the CLI (hicain-cli), and the Web UI (hicain-webui), along with all configuration parameters, commands, and operational procedures.

Relationship: Both the CLI and Web UI are clients of the management socket API. They do not contain any switching logic, they translate user actions into JSON commands and display responses.

1. Management Socket API¶

1.1 Connection Details¶

Parameter	Value
Socket type	UNIX domain socket, `SOCK_STREAM`
Default path	`/var/run/hicain/mgmt.sock`
Protocol	Newline-delimited JSON (one JSON object per `\n`-terminated line)
Pattern	Synchronous request-response
Concurrency	Multiple clients may connect simultaneously; each request is processed atomically by the single-threaded event loop

1.2 Request Format¶

Every request is a single JSON object with a cmd field and command-specific parameters:

{"cmd": "<command_name>", "param1": "value1", "param2": "value2"}\n

1.3 Response Format¶

Every response is a single JSON object. On success, it includes "status": "ok". On error, it includes "status": "error" and an "error" message:

// Success
{"status": "ok", ...response_data...}\n

// Error
{"status": "error", "error": "Invalid port number: 99"}\n

2. Port Management Commands¶

2.1 `port_status`, Query Port Status¶

Retrieve the current status, configuration, and counters for one or all ports.

Request:

// Single port
{"cmd": "port_status", "port": 0}

// All ports (omit port parameter)
{"cmd": "port_status"}

Response (single port):

href="#__codelineno-3-1">{ "status": "ok", "port": 0, "role": "FABRIC", "link_state": "UP", "mode": "AUTO", "mac": "02:00:00:00:00:01", "pfc_enabled": [false, false, false, true, true, false, false, false], "ecn": { "enabled": true, "marking_threshold": 32768, "marking_probability": 10 }, "ets": { "prio_to_tc": [0, 0, 0, 3, 3, 0, 0, 7], "tc_bandwidth": [50, 0, 0, 50, 0, 0, 0, 0], "tc_tsa": ["ets", "strict", "strict", "ets", "strict", "strict", "strict", "strict"] }, "stats": { "rx_frames": 15432, "tx_frames": 15100, "rx_bytes": 4523100, "tx_bytes": 4418000, "rx_drops": 3, "tx_drops": 0, "pfc_pause_sent": 12, "pfc_pause_received": 8, "ecn_marked": 42, "classify_errors": 0 } }

Response (all ports):

{
    "status": "ok",
    "ports": [
        {"port": 0, "role": "FABRIC", "link_state": "UP", "mode": "AUTO", ...},
        {"port": 1, "role": "FABRIC", "link_state": "DOWN", "mode": "AUTO", ...},
        ...
        {"port": 8, "role": "UPLINK", "link_state": "UP", "mode": "STRICT_ETH", ...},
        {"port": 9, "role": "CONSOLE", "link_state": "UP", "mode": null, ...}
    ]
}

CLI equivalent:

hicain-cli port status          # All ports
hicain-cli port status 0        # Single port
hicain-cli port status --json   # Machine-readable output

Web UI equivalent:

GET /api/ports          → All ports
GET /api/ports/0        → Single port

2.2 `set_port_mode`, Set Port Operating Mode¶

Configure how a fabric port classifies incoming frames.

Request:

{"cmd": "set_port_mode", "port": 0, "mode": "STRICT_ETH"}

Parameters:

Parameter	Type	Required	Values	Description
`port`	integer	Yes	0, 7	Fabric port number (uplink/console ports cannot be changed)
`mode`	string	Yes	`STRICT_ETH`, `STRICT_IB`, `AUTO`	Frame classification mode

Constraints: - Port 8 (UPLINK) is always STRICT_ETH, attempting to change it returns an error - Port 9 (CONSOLE) has no data-plane mode, attempting to change it returns an error

Response:

{"status": "ok", "port": 0, "mode": "STRICT_ETH"}

CLI equivalent:

hicain-cli port set-mode 0 STRICT_ETH
hicain-cli port set-mode 2 AUTO
hicain-cli port set-mode 5 STRICT_IB

Web UI equivalent:

PUT /api/ports/0/mode
Body: {"mode": "STRICT_ETH"}

2.3 `set_link_state`, Administratively Set Link State¶

Bring a port administratively up or down. This is independent of whether an endpoint is physically connected.

Request:

{"cmd": "set_link_state", "port": 0, "state": "DOWN"}

Parameters:

Parameter	Type	Required	Values	Description
`port`	integer	Yes	0, 8	Port number (console port excluded)
`state`	string	Yes	`UP`, `DOWN`	Administrative link state

Side effects of DOWN: - All frames to/from this port are dropped - FDB entries learned on this port are flushed - PFC state is reset for this port - The connected endpoint is not disconnected, when set back to UP, traffic resumes

Response:

{"status": "ok", "port": 0, "link_state": "DOWN"}

CLI equivalent:

hicain-cli port link-down 0
hicain-cli port link-up 0

Web UI equivalent:

PUT /api/ports/0/link
Body: {"state": "DOWN"}

3. DCB Configuration Commands¶

3.1 `set_pfc`, Configure Priority Flow Control¶

Enable or disable PFC on specific priorities for a fabric port.

Request:

{"cmd": "set_pfc", "port": 0, "priorities": [3, 4], "enabled": true}

Parameters:

Parameter	Type	Required	Values	Description
`port`	integer	Yes	0, 7	Fabric port number
`priorities`	array[int]	Yes	0, 7	List of priority values to configure
`enabled`	boolean	Yes	`true`, `false`	Enable or disable PFC for these priorities

Constraints: - PFC is only supported on FABRIC ports (0, 7) - Uplink port (8) does not support PFC, returns an error - PFC priorities must be in range 0, 7

Response:

{"status": "ok", "port": 0, "pfc_enabled": [false, false, false, true, true, false, false, false]}

CLI equivalent:

hicain-cli pfc enable 0 --priorities 3,4
hicain-cli pfc disable 0 --priorities 0,1,2,5,6,7
hicain-cli pfc status 0

Web UI equivalent:

PUT /api/ports/0/pfc
Body: {"priorities": [3, 4], "enabled": true}

GET /api/ports/0/pfc

3.2 `set_ets`, Configure Enhanced Transmission Selection¶

Set the priority-to-TC mapping, bandwidth allocation, and scheduling algorithm per TC.

Request:

{
    "cmd": "set_ets",
    "port": 0,
    "prio_to_tc": [0, 0, 0, 3, 3, 0, 0, 7],
    "tc_bandwidth": [50, 0, 0, 50, 0, 0, 0, 0],
    "tc_tsa": ["ets", "strict", "strict", "ets", "strict", "strict", "strict", "strict"]
}

Parameters:

Parameter	Type	Required	Values	Description
`port`	integer	Yes	0, 7	Fabric port number
`prio_to_tc`	array[int]	Yes	8 elements, each 0, 7	Maps priority N → TC
`tc_bandwidth`	array[int]	Yes	8 elements, must sum to 100 for ETS TCs	Bandwidth % per TC
`tc_tsa`	array[string]	Yes	8 elements: `"ets"` or `"strict"`	Scheduling algorithm per TC

Validation rules: - tc_bandwidth values for TCs with "strict" TSA must be 0 - tc_bandwidth values for TCs with "ets" TSA must sum to 100 - All arrays must have exactly 8 elements

Response:

{
    "status": "ok",
    "port": 0,
    "ets": {
        "prio_to_tc": [0, 0, 0, 3, 3, 0, 0, 7],
        "tc_bandwidth": [50, 0, 0, 50, 0, 0, 0, 0],
        "tc_tsa": ["ets", "strict", "strict", "ets", "strict", "strict", "strict", "strict"]
    }
}

CLI equivalent:

hicain-cli ets set 0 \
    --prio-tc 0:0,1:0,2:0,3:3,4:3,5:0,6:0,7:7 \
    --tc-bw 0:50,3:50 \
    --tc-tsa 0:ets,3:ets,7:strict

hicain-cli ets status 0

Web UI equivalent:

PUT /api/ports/0/ets
Body: {"prio_to_tc": [...], "tc_bandwidth": [...], "tc_tsa": [...]}

GET /api/ports/0/ets

3.3 `set_ecn`, Configure Explicit Congestion Notification¶

Enable ECN marking and set marking thresholds for a fabric port.

Request:

{"cmd": "set_ecn", "port": 0, "enabled": true, "marking_threshold": 32768, "marking_probability": 10}

Parameters:

Parameter	Type	Required	Values	Description
`port`	integer	Yes	0, 7	Fabric port number
`enabled`	boolean	Yes	`true`, `false`	Enable or disable ECN marking
`marking_threshold`	integer	Conditional	> 0 (bytes)	Queue depth at which marking begins (required when `enabled=true`)
`marking_probability`	integer	Conditional	1, 100 (%)	Probability of marking when above threshold (required when `enabled=true`)

Response:

{
    "status": "ok",
    "port": 0,
    "ecn": {
        "enabled": true,
        "marking_threshold": 32768,
        "marking_probability": 10
    }
}

CLI equivalent:

hicain-cli ecn set 0 --enable --threshold 32768 --probability 10
hicain-cli ecn set 0 --disable
hicain-cli ecn status 0

Web UI equivalent:

PUT /api/ports/0/ecn
Body: {"enabled": true, "marking_threshold": 32768, "marking_probability": 10}

GET /api/ports/0/ecn

4. Forwarding Table Commands¶

4.1 `fdb_add`, Add Static MAC FDB Entry¶

Add a static entry to the MAC forwarding database.

Request:

{"cmd": "fdb_add", "mac": "02:00:00:00:00:01", "vlan": 100, "port": 0}

Parameters:

Parameter	Type	Required	Values	Description
`mac`	string	Yes	`XX:XX:XX:XX:XX:XX`	MAC address
`vlan`	integer	Yes	0, 4094 (0 = untagged)	VLAN ID
`port`	integer	Yes	0, 8	Egress port number

Response:

{"status": "ok", "mac": "02:00:00:00:00:01", "vlan": 100, "port": 0, "type": "static"}

CLI equivalent:

hicain-cli fdb add --mac 02:00:00:00:00:01 --vlan 100 --port 0

Web UI equivalent:

POST /api/fdb
Body: {"mac": "02:00:00:00:00:01", "vlan": 100, "port": 0}

4.2 `fdb_del`, Delete MAC FDB Entry¶

Remove a MAC forwarding database entry (static or learned).

Request:

{"cmd": "fdb_del", "mac": "02:00:00:00:00:01", "vlan": 100}

Parameters:

Parameter	Type	Required	Values	Description
`mac`	string	Yes	`XX:XX:XX:XX:XX:XX`	MAC address
`vlan`	integer	Yes	0, 4094	VLAN ID

Response:

{"status": "ok", "mac": "02:00:00:00:00:01", "vlan": 100, "deleted": true}

CLI equivalent:

hicain-cli fdb del --mac 02:00:00:00:00:01 --vlan 100

Web UI equivalent:

DELETE /api/fdb
Body: {"mac": "02:00:00:00:00:01", "vlan": 100}

4.3 `fdb_dump`, Dump MAC Forwarding Database¶

List all entries in the MAC forwarding database.

Request:

{"cmd": "fdb_dump"}

Response:

{
    "status": "ok",
    "entries": [
        {"mac": "02:00:00:00:00:01", "vlan": 100, "port": 0, "type": "static", "age": 0},
        {"mac": "02:00:00:00:00:02", "vlan": 100, "port": 1, "type": "learned", "age": 45},
        {"mac": "02:00:00:00:00:05", "vlan": 0,   "port": 3, "type": "learned", "age": 12}
    ],
    "count": 3
}

Entry fields:

Field	Description
`type`	`"static"` (manually added) or `"learned"` (auto-discovered from source MAC)
`age`	Seconds since last seen (learned entries only; static entries always 0)

CLI equivalent:

hicain-cli fdb show
hicain-cli fdb show --json

CLI output (table format):

MAC                VLAN  PORT  TYPE     AGE
─────────────────  ────  ────  ───────  ───
02:00:00:00:00:01  100   0     static   —
02:00:00:00:00:02  100   1     learned  45s
02:00:00:00:00:05  0     3     learned  12s

3 entries

Web UI equivalent:

GET /api/fdb

4.4 `lft_add`, Add IB LID Forwarding Table Entry¶

Add a static entry to the InfiniBand LID forwarding table.

Request:

{"cmd": "lft_add", "dlid": 1, "port": 0}

Parameters:

Parameter	Type	Required	Values	Description
`dlid`	integer	Yes	1, 65535	Destination LID
`port`	integer	Yes	0, 7	Egress fabric port number

Response:

{"status": "ok", "dlid": 1, "port": 0}

CLI equivalent:

hicain-cli lft add --dlid 1 --port 0

Web UI equivalent:

POST /api/lft
Body: {"dlid": 1, "port": 0}

4.5 `lft_del`, Delete IB LFT Entry¶

Request:

{"cmd": "lft_del", "dlid": 1}

Response:

{"status": "ok", "dlid": 1, "deleted": true}

CLI equivalent:

hicain-cli lft del --dlid 1

Web UI equivalent:

DELETE /api/lft
Body: {"dlid": 1}

4.6 `lft_dump`, Dump IB LID Forwarding Table¶

Request:

{"cmd": "lft_dump"}

Response:

{
    "status": "ok",
    "entries": [
        {"dlid": 1, "port": 0},
        {"dlid": 2, "port": 1},
        {"dlid": 10, "port": 6}
    ],
    "count": 3
}

CLI equivalent:

hicain-cli lft show

CLI output (table format):

DLID  PORT
────  ────
1     0
2     1
10    6

3 entries

Web UI equivalent:

GET /api/lft

5. Telemetry Commands¶

5.1 `telemetry_dump`, Dump All Port Counters¶

Retrieve all telemetry counters for all ports in a single response.

Request:

{"cmd": "telemetry_dump"}

Response:

{
    "status": "ok",
    "ports": [
        {
            "port": 0, "role": "FABRIC",
            "rx_frames": 15432, "tx_frames": 15100,
            "rx_bytes": 4523100, "tx_bytes": 4418000,
            "rx_drops": 3, "tx_drops": 0,
            "pfc_pause_sent": 12, "pfc_pause_received": 8,
            "ecn_marked": 42, "classify_errors": 0,
            "queues": [
                {"priority": 0, "occupancy": 1024, "buffer_size": 65536},
                {"priority": 3, "occupancy": 48000, "buffer_size": 65536},
                ...
            ]
        },
        ...
    ],
    "fdb_entries": 42,
    "lft_entries": 8
}

CLI equivalent:

hicain-cli telemetry show
hicain-cli telemetry show --json

Web UI equivalent:

GET /api/telemetry
WebSocket /ws/telemetry    → Real-time streaming (polled every 1s)

5.2 `telemetry_clear`, Reset All Counters¶

Reset all port telemetry counters to zero.

Request:

{"cmd": "telemetry_clear"}

Response:

{"status": "ok", "cleared": true}

CLI equivalent:

hicain-cli telemetry clear

Web UI equivalent:

POST /api/telemetry/clear

6. CLI Reference, `hicain-cli`¶

6.1 Installation & Requirements¶

# Install via Poetry (from project root)
poetry install

# Or install CLI package directly
pip install -e ./cli

Dependencies (managed by Poetry): - Python 3.10+ - typer[all], CLI framework with auto-completion - rich, terminal formatting (tables, syntax highlighting) - pydantic, data validation & serialization - asyncio, async I/O (stdlib)

6.2 Global Options¶

Option	Default	Description
`--socket PATH`	`/var/run/hicain/mgmt.sock`	Path to the management UNIX socket
`--json`	Off	Output in JSON format instead of human-readable tables
`--timeout SECS`	`5`	Connection/response timeout in seconds
`--help`		Show help message

6.3 Complete Command Reference¶

hicain-cli [global-options] <command-group> <action> [arguments] [options]

Port Commands¶

Command	Description
`port status`	Show all ports
`port status <PORT>`	Show single port details
`port set-mode <PORT> <MODE>`	Set port mode (`STRICT_ETH`, `STRICT_IB`, `AUTO`)
`port link-up <PORT>`	Administratively bring port up
`port link-down <PORT>`	Administratively bring port down

PFC Commands¶

Command	Description
`pfc status <PORT>`	Show PFC state per priority
`pfc enable <PORT> --priorities P1,P2,...`	Enable PFC on specified priorities
`pfc disable <PORT> --priorities P1,P2,...`	Disable PFC on specified priorities

ETS Commands¶

Command	Description
`ets status <PORT>`	Show ETS configuration
`ets set <PORT> --prio-tc MAP --tc-bw MAP --tc-tsa MAP`	Configure ETS (see §3.2)

ECN Commands¶

Command	Description
`ecn status <PORT>`	Show ECN configuration
`ecn set <PORT> --enable --threshold N --probability N`	Enable and configure ECN
`ecn set <PORT> --disable`	Disable ECN

FDB Commands¶

Command	Description
`fdb show`	Dump MAC forwarding database
`fdb add --mac MAC --vlan VLAN --port PORT`	Add static FDB entry
`fdb del --mac MAC --vlan VLAN`	Delete FDB entry

LFT Commands¶

Command	Description
`lft show`	Dump IB LID forwarding table
`lft add --dlid DLID --port PORT`	Add LFT entry
`lft del --dlid DLID`	Delete LFT entry

Telemetry Commands¶

Command	Description
`telemetry show`	Dump all port counters
`telemetry clear`	Reset all counters to zero

6.4 Exit Codes¶

Code	Meaning
`0`	Success
`1`	Command error (invalid arguments, validation failure)
`2`	Connection error (cannot connect to management socket)
`3`	Switch error (switch returned an error response)

7. Web UI Reference, `hicain-webui`¶

7.1 Installation & Requirements¶

# Backend (Python — via Poetry)
poetry install

# Frontend (Next.js)
cd webui/frontend && npm install

Backend dependencies (Poetry): - Python 3.10+ - fastapi, async web framework - uvicorn, ASGI server - pydantic, request/response validation - websockets, WebSocket support

Frontend dependencies (npm): - Next.js 14+ - React 18+ - TypeScript - Recharts, telemetry charts - React Flow, topology diagrams - Tailwind CSS, styling - shadcn/ui, UI components

7.2 Startup Options¶

hicain-webui [options]

Option	Environment Variable	Default	Description
`--socket PATH`	`HICAIN_MGMT_SOCKET`	`/var/run/hicain/mgmt.sock`	Management socket path
`--listen ADDR:PORT`	`HICAIN_WEBUI_LISTEN`	`0.0.0.0:8080`	Listen address
`--log-level LEVEL`	`HICAIN_LOG_LEVEL`	`info`	Log verbosity

7.3 REST API Reference¶

All endpoints return JSON. Error responses follow the format:

{"detail": "Error message", "status_code": 400}

Port Endpoints¶

Method	Path	Description	Request Body
`GET`	`/api/ports`	List all 10 ports	,
`GET`	`/api/ports/{id}`	Single port details	,
`PUT`	`/api/ports/{id}/mode`	Set port mode	`{"mode": "AUTO"}`
`PUT`	`/api/ports/{id}/link`	Set link state	`{"state": "UP"}`

DCB Endpoints¶

Method	Path	Description	Request Body
`GET`	`/api/ports/{id}/pfc`	Get PFC status	,
`PUT`	`/api/ports/{id}/pfc`	Configure PFC	`{"priorities": [3,4], "enabled": true}`
`GET`	`/api/ports/{id}/ets`	Get ETS config	,
`PUT`	`/api/ports/{id}/ets`	Configure ETS	See §3.2
`GET`	`/api/ports/{id}/ecn`	Get ECN config	,
`PUT`	`/api/ports/{id}/ecn`	Configure ECN	See §3.3

Forwarding Table Endpoints¶

Method	Path	Description	Request Body
`GET`	`/api/fdb`	Dump MAC FDB	,
`POST`	`/api/fdb`	Add FDB entry	`{"mac": "...", "vlan": 100, "port": 0}`
`DELETE`	`/api/fdb`	Delete FDB entry	`{"mac": "...", "vlan": 100}`
`GET`	`/api/lft`	Dump IB LFT	,
`POST`	`/api/lft`	Add LFT entry	`{"dlid": 1, "port": 0}`
`DELETE`	`/api/lft`	Delete LFT entry	`{"dlid": 1}`

Telemetry Endpoints¶

Method	Path	Description
`GET`	`/api/telemetry`	Dump all counters
`POST`	`/api/telemetry/clear`	Reset all counters
`WebSocket`	`/ws/telemetry`	Real-time telemetry stream (JSON, 1s interval)

7.4 WebSocket Telemetry Stream¶

Connect to /ws/telemetry for real-time counter updates:

const ws = new WebSocket("ws://localhost:8080/ws/telemetry");

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    // data has same format as GET /api/telemetry response
    // Pushed every 1 second
};

Control messages (client → server):

// Change update interval (default: 1s)
{"cmd": "set_interval", "interval_ms": 2000}

// Subscribe to specific ports only
{"cmd": "subscribe", "ports": [0, 1, 6, 7]}

7.5 Dashboard Pages¶

Page	URL Path	Description
Overview	`/`	Visual 10-port switch front panel with live LED indicators, role badges, and RX/TX sparklines
Port Detail	`/port/{id}`	Single-port deep dive: mode config, DCB settings (PFC/ETS/ECN), per-priority queue occupancy gauges
Forwarding Tables	`/tables`	Searchable/sortable MAC FDB and IB LFT tables with inline add/delete
Telemetry	`/telemetry`	Real-time charts: frame rates, byte throughput, PFC PAUSE events, ECN marks (configurable time window)
Topology	`/topology`	Visual TOR-to-TOR interconnect diagram showing VM and ISL connections

7.6 Auto-Generated API Documentation¶

FastAPI automatically generates interactive API documentation:

URL	Format
`/docs`	Swagger UI (interactive)
`/redoc`	ReDoc (read-only, clean layout)
`/openapi.json`	Raw OpenAPI 3.0 schema

8. Configuration Files¶

8.1 Switch Daemon, `hicain-vswitchd`¶

The switch daemon is configured via command-line arguments and environment variables. There is no configuration file for v1, all persistent config is set via the management API at runtime.

Daemon CLI Options¶

hicain-vswitchd [options]

Option	Environment Variable	Default	Description
`--run-dir DIR`	`HICAIN_RUN_DIR`	`/var/run/hicain`	Directory for UNIX sockets
`--otel-endpoint URL`	`HICAIN_OTEL_ENDPOINT`	`http://localhost:4318`	OTLP HTTP collector endpoint
`--otel-interval SECS`	`HICAIN_OTEL_INTERVAL`	`10`	Telemetry export interval
`--switch-id ID`	`HICAIN_SWITCH_ID`	`$(hostname)`	Unique switch identifier
`--log-level LEVEL`	`HICAIN_LOG_LEVEL`	`info`	`debug`, `info`, `warn`, `error`
`--foreground`	,	Off	Run in foreground (don't daemonize)
`--fdb-aging SECS`	`HICAIN_FDB_AGING`	`300`	MAC FDB aging timeout (0 = disabled)
`--pfc-xoff-threshold BYTES`	`HICAIN_PFC_XOFF`	`49152`	Default PFC XOFF threshold per queue
`--pfc-xon-threshold BYTES`	`HICAIN_PFC_XON`	`16384`	Default PFC XON threshold per queue
`--queue-buffer-size BYTES`	`HICAIN_QUEUE_BUF`	`65536`	Default per-priority queue buffer size

8.2 Environment Variable Summary¶

All components respect these environment variables (12-factor style):

Variable	Used By	Default	Description
`HICAIN_RUN_DIR`	daemon	`/var/run/hicain`	Socket directory
`HICAIN_SWITCH_ID`	daemon	`$(hostname)`	Switch identifier for OTel
`HICAIN_OTEL_ENDPOINT`	daemon	`http://localhost:4318`	OTLP collector URL
`HICAIN_OTEL_INTERVAL`	daemon	`10`	OTel export interval (seconds)
`HICAIN_LOG_LEVEL`	all	`info`	Log verbosity
`HICAIN_MGMT_SOCKET`	cli, webui	`/var/run/hicain/mgmt.sock`	Management socket path
`HICAIN_WEBUI_LISTEN`	webui	`0.0.0.0:8080`	Web UI listen address
`HICAIN_NO_WEBUI`	entrypoint	(unset)	Disable Web UI in container
`HICAIN_ISL_SOCK_DIR`	daemon	(unset)	ISL socket directory override
`HICAIN_FDB_AGING`	daemon	`300`	FDB aging timeout
`HICAIN_PFC_XOFF`	daemon	`49152`	Default PFC XOFF threshold
`HICAIN_PFC_XON`	daemon	`16384`	Default PFC XON threshold
`HICAIN_QUEUE_BUF`	daemon	`65536`	Default queue buffer size

9. Typical Operational Workflows¶

9.1 Initial RoCEv2 Setup¶

Configure a port for lossless RoCEv2 traffic:

# 1. Set port mode to Ethernet
hicain-cli port set-mode 0 STRICT_ETH

# 2. Enable PFC on priority 3 (RDMA traffic class)
hicain-cli pfc enable 0 --priorities 3

# 3. Configure ETS: 50% to RDMA (TC3), 50% to best-effort (TC0)
hicain-cli ets set 0 \
    --prio-tc 0:0,1:0,2:0,3:3,4:0,5:0,6:0,7:7 \
    --tc-bw 0:50,3:50 \
    --tc-tsa 0:ets,3:ets,7:strict

# 4. Enable ECN marking
hicain-cli ecn set 0 --enable --threshold 32768 --probability 10

# 5. Verify
hicain-cli port status 0

9.2 InfiniBand Static Routing¶

Configure ports for InfiniBand with static LID routing:

# 1. Set ports to IB mode
hicain-cli port set-mode 0 STRICT_IB
hicain-cli port set-mode 1 STRICT_IB

# 2. Assign LID routes
hicain-cli lft add --dlid 1 --port 0    # LID 1 → port 0
hicain-cli lft add --dlid 2 --port 1    # LID 2 → port 1

# 3. Verify
hicain-cli lft show

9.3 TOR-to-TOR Aggregation¶

Connect two switches via ISL ports 6, 7:

# On Switch A:
hicain-cli port set-mode 6 AUTO
hicain-cli port set-mode 7 AUTO
hicain-cli pfc enable 6 --priorities 3
hicain-cli pfc enable 7 --priorities 3

# Add LFT entries for remote LIDs (on Switch B)
hicain-cli lft add --dlid 10 --port 6   # Remote LID 10 → ISL port 6

# On Switch B: mirror configuration
hicain-cli port set-mode 6 AUTO
hicain-cli port set-mode 7 AUTO
hicain-cli lft add --dlid 1 --port 6    # Remote LID 1 → ISL port 6

9.4 Monitoring & Troubleshooting¶

# Live counter summary
hicain-cli telemetry show

# Check for PFC storms (excessive pauses)
hicain-cli pfc status 0

# Check for drops (indicates misconfiguration)
hicain-cli port status 0 | grep drops

# Inspect learned MACs
hicain-cli fdb show

# Reset counters for a clean measurement
hicain-cli telemetry clear

HiCAIN Control Plane Reference¶

1. Management Socket API¶

1.1 Connection Details¶

1.2 Request Format¶

1.3 Response Format¶

2. Port Management Commands¶

2.1 port_status, Query Port Status¶

2.2 set_port_mode, Set Port Operating Mode¶

2.3 set_link_state, Administratively Set Link State¶

3. DCB Configuration Commands¶

3.1 set_pfc, Configure Priority Flow Control¶

3.2 set_ets, Configure Enhanced Transmission Selection¶

3.3 set_ecn, Configure Explicit Congestion Notification¶

4. Forwarding Table Commands¶

4.1 fdb_add, Add Static MAC FDB Entry¶

4.2 fdb_del, Delete MAC FDB Entry¶

4.3 fdb_dump, Dump MAC Forwarding Database¶

4.4 lft_add, Add IB LID Forwarding Table Entry¶

4.5 lft_del, Delete IB LFT Entry¶

4.6 lft_dump, Dump IB LID Forwarding Table¶

5. Telemetry Commands¶

5.1 telemetry_dump, Dump All Port Counters¶

5.2 telemetry_clear, Reset All Counters¶

6. CLI Reference, hicain-cli¶

6.1 Installation & Requirements¶

6.2 Global Options¶

6.3 Complete Command Reference¶

Port Commands¶

PFC Commands¶

ETS Commands¶

ECN Commands¶

FDB Commands¶

LFT Commands¶

Telemetry Commands¶

6.4 Exit Codes¶

7. Web UI Reference, hicain-webui¶

7.1 Installation & Requirements¶

7.2 Startup Options¶

7.3 REST API Reference¶

Port Endpoints¶

DCB Endpoints¶

Forwarding Table Endpoints¶

Telemetry Endpoints¶

7.4 WebSocket Telemetry Stream¶

7.5 Dashboard Pages¶

7.6 Auto-Generated API Documentation¶

8. Configuration Files¶

8.1 Switch Daemon, hicain-vswitchd¶

Daemon CLI Options¶

8.2 Environment Variable Summary¶

9. Typical Operational Workflows¶

9.1 Initial RoCEv2 Setup¶

9.2 InfiniBand Static Routing¶

9.3 TOR-to-TOR Aggregation¶

9.4 Monitoring & Troubleshooting¶

2.1 `port_status`, Query Port Status¶

2.2 `set_port_mode`, Set Port Operating Mode¶

2.3 `set_link_state`, Administratively Set Link State¶

3.1 `set_pfc`, Configure Priority Flow Control¶

3.2 `set_ets`, Configure Enhanced Transmission Selection¶

3.3 `set_ecn`, Configure Explicit Congestion Notification¶

4.1 `fdb_add`, Add Static MAC FDB Entry¶

4.2 `fdb_del`, Delete MAC FDB Entry¶

4.3 `fdb_dump`, Dump MAC Forwarding Database¶

4.4 `lft_add`, Add IB LID Forwarding Table Entry¶

4.5 `lft_del`, Delete IB LFT Entry¶

4.6 `lft_dump`, Dump IB LID Forwarding Table¶

5.1 `telemetry_dump`, Dump All Port Counters¶

5.2 `telemetry_clear`, Reset All Counters¶

6. CLI Reference, `hicain-cli`¶

7. Web UI Reference, `hicain-webui`¶

8.1 Switch Daemon, `hicain-vswitchd`¶