> For the complete documentation index, see [llms.txt](https://asus-isg-aidc.gitbook.io/guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://asus-isg-aidc.gitbook.io/guide/latest/cli/commandreference/networkvalidation.md).

# Network Validation

| Developer | Last modified |
| --------- | ------------- |
| AIDC Team | 2026/07/06    |

## Table of Contents

* [1. Overview](#overview)
* [2. Subcommands](#subcommands)
* [3. Common Output Flag](#common-output-flag)
* [4. Usage Examples](#usage-examples)

***

## 1. Overview <a href="#overview" id="overview"></a>

{% hint style="warning" %}
**⚠️ Prerequisite: `aidc-cli init` required first**

This command depends on settings saved by [`aidc-cli init`](/guide/latest/cli/commandreference/init.md). Before running it, make sure you have completed:

* [`aidc-cli init inventory`](/guide/latest/cli/commandreference/init.md#inventory) — render the node inventory from `aidc.csv`
* SSH access to the nodes — [`aidc-cli deploy install`](/guide/latest/cli/commandreference/deploy.md) sets this up during OS deployment; for nodes that already have an OS, run [`aidc-cli deploy access-key`](/guide/latest/cli/commandreference/deploy.md) or fill the `password` column in `aidc.csv`

For the full setup sequence, see the [Getting Started](/guide/latest/cli/gettingstarted.md) guide.
{% endhint %}

The `chknet` (check network) command validates network connectivity across the infrastructure — verifying PXE, BMC, and InfiniBand networks, and mapping Ethernet port layouts.

```bash
aidc-cli chknet <subcommand> [flags]
```

All subcommands support `--stdout` (`-o`) flag for JSON output.

***

## 2. Subcommands <a href="#subcommands" id="subcommands"></a>

### 2.1 `pxe` — Validate PXE Network

Tests connectivity on the PXE provisioning network between the AIDC Server and client nodes.

```bash
aidc-cli chknet pxe [-o]
```

| Flag       | Short | Required | Description                           |
| ---------- | :---: | :------: | ------------------------------------- |
| `--stdout` |  `-o` |     ❌    | Output report to stdout (JSON format) |

{% hint style="info" %}
All client nodes generated by the `aidc.csv` file which are configured through the OS installed by AIDC will be tested at once. The report will be generated at: `reports/net-conn/CLI_chknet_pxe_YYYY-MM-DD_HH-MM-SS.json`
{% endhint %}

***

### 2.2 `bmc` — Validate BMC Network

Tests BMC/IPMI network connectivity to all managed nodes.

```bash
aidc-cli chknet bmc [-o]
```

| Flag       | Short | Required | Description                           |
| ---------- | :---: | :------: | ------------------------------------- |
| `--stdout` |  `-o` |     ❌    | Output report to stdout (JSON format) |

{% hint style="info" %}
The report will be generated at: `reports/net-conn/CLI_chknet_bmc_YYYY-MM-DD_HH-MM-SS.json`. Each new report execution creates a unique timestamped file.
{% endhint %}

***

### 2.3 `ib` — Validate InfiniBand Network

Tests InfiniBand fabric connectivity and link status.

```bash
aidc-cli chknet ib [-o] [-f <format>]
```

| Flag       | Short | Required | Description                                                            |
| ---------- | :---: | :------: | ---------------------------------------------------------------------- |
| `--stdout` |  `-o` |     ❌    | Output report to stdout (JSON format)                                  |
| `--format` |  `-f` |     ❌    | Report format: `host` (group by host) or `device` (group by IB device) |

{% hint style="info" %}
The InfiniBand report supports two output formats:

* **Default** (by\_device): `aidc-cli chknet ib -f device`
* **Host-grouped** (by\_host): `aidc-cli chknet ib -f host`

The report will be generated at: `reports/net-conn/CLI_chknet_ib_YYYY-MM-DD_HH-MM-SS.json`. Ensure that the deployment host has an InfiniBand interface and map an additional interface to the AIDC Server VM in `deployment/kvm.yml` (see [Installation & Setup](/guide/latest/installation.md#deploying-with-aidc-deploy)).
{% endhint %}

***

### 2.4 `eth-map` — Ethernet Port Mapping

Maps physical Ethernet ports to logical device names across all nodes.

```bash
aidc-cli chknet eth-map [-o]
```

| Flag       | Short | Required | Description                           |
| ---------- | :---: | :------: | ------------------------------------- |
| `--stdout` |  `-o` |     ❌    | Output report to stdout (JSON format) |

{% hint style="info" %}
Refer to the "Common" & "Group" section in the `init` documentation and ensure that the device is added to the switches group and listed in the `aidc.csv` file. The report will be generated at: `reports/port-mapping/CLI_chknet_eth-map_YYYY-MM-DD_HH-MM-SS.json` (JSON) and `reports/port-mapping/CLI_chknet_eth-map_YYYY-MM-DD_HH-MM-SS.html` (HTML).
{% endhint %}

***

## 3. Common Output Flag <a href="#common-output-flag" id="common-output-flag"></a>

All `chknet` subcommands support `--stdout` (`-o`) to redirect the report to standard output in JSON format. This is useful for:

* Piping to `jq` for processing
* Integration with monitoring systems
* Automated validation scripts

```bash
# JSON output example
aidc-cli chknet pxe -o | jq '.results[] | select(.status == "failed")'
```

***

## 4. Usage Examples <a href="#usage-examples" id="usage-examples"></a>

```bash
# Quick network health check
aidc-cli chknet pxe
aidc-cli chknet bmc

# InfiniBand validation grouped by device
aidc-cli chknet ib -f device

# Ethernet port mapping for specific nodes
aidc-cli chknet eth-map -l node01,node02

# Output all validation results as JSON
aidc-cli chknet pxe -o > pxe-report.json
aidc-cli chknet bmc -o > bmc-report.json
```