> 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/installation.md).

# Installation & Setup

| Developer | Last modified |
| --------- | ------------- |
| AIDC Team | 2026/08/20    |

## Overview

AIDC-CLI (ASUS Infrastructure Deployment Center-CLI) provides a stable and consistent configuration for automating and managing nodes efficiently. AIDC-Portal provides the same platform capabilities through a browser-based interface for day-to-day operations. Both ship as **pre-built QCOW2 images** bundled in a single release package, and are deployed onto a KVM/libvirt host using **`aidc-deploy`** — a standalone deployment tool included in that package.

{% hint style="info" %}
`aidc-deploy` is a single Go executable. It requires no separate language runtime, and it deploys directly from the QCOW2 images — there is no separate install step for either VM.
{% endhint %}

***

## Prerequisites

### 1. Deployment Host Requirements

The machine you run `aidc-deploy` on (the **deployment host**) must be:

* **Ubuntu 24.04 LTS** — `aidc-deploy` checks this before starting and aborts on any other OS or version.
* Able to reach the local KVM/libvirt service.
* Run with root or sudo access, since dependency installation and VM management require elevated privileges.

`aidc-deploy` automatically detects and installs any missing dependencies via `apt`. It aborts deployment if installation or verification of any of the following fails:

| Function            | Ubuntu 24.04 Package    | Command     |
| ------------------- | ----------------------- | ----------- |
| SHA256 verification | `coreutils`             | `sha256sum` |
| Archive extraction  | `tar`                   | `tar`       |
| QCOW2 management    | `qemu-utils`            | `qemu-img`  |
| QEMU/KVM            | `qemu-system-x86`       | —           |
| libvirt daemon      | `libvirt-daemon-system` | `libvirtd`  |
| libvirt CLI         | `libvirt-clients`       | `virsh`     |

### 2. Obtain and Extract the Deployment Package

AIDC-CLI and AIDC-Portal are distributed together as a single package, `aidc.tar.gz`, which includes both QCOW2 images.

{% hint style="info" %}
Contact your AIDC administrator if the package is not available.
{% endhint %}

Extract the package on the deployment host:

```bash
tar -xzf aidc.tar.gz
cd aidc
```

The extracted package is laid out as follows:

```
aidc/
├── aidc-deploy
├── config.yml
├── images/
│   ├── aidc-cli.qcow2
│   ├── aidc-cli.qcow2.sha256
│   ├── aidc-portal.qcow2
│   └── aidc-portal.qcow2.sha256
└── deployment/
    └── kvm.yml
```

`config.yml` and `deployment/kvm.yml` are provided as default configuration files — Interactive Mode (below) updates and saves them rather than generating them from scratch.

### 3. Deployment Location

Extract/place the package outside `/root` (e.g. `/opt/aidc`), not inside it.

QEMU runs as the unprivileged `libvirt-qemu` user, which cannot traverse into `/root` at all — `/root` is `700` by default, and that's an OS-level directory-traversal boundary, not something fixable by `chmod`/`chown` on the QCOW2 files themselves. `aidc-deploy` pre-flight-checks this before creating each VM's overlay disk and aborts with:

```
[ERROR] QEMU (running as "libvirt-qemu") cannot read /root/aidc/aidc-portal.qcow2.
Extract the deployment package outside restricted directories like /root
(e.g. /opt/aidc) so QEMU can access the image
```

If you hit this after already extracting under `/root`, move the whole package (not just the images) outside it, e.g.:

```bash
mv /root/aidc /opt/aidc
```

{% hint style="warning" %}
If `images/` holds symlinks into a shared image directory rather than the files themselves, recreate those symlinks afterward — a plain `mv` preserves symlinks as-is, so absolute-path symlinks pointing at the old `/root/...` location will dangle until re-pointed at the new path.
{% endhint %}

***

## System Requirements

### VM Sizing

The following sizing applies to both the `aidc-cli` and `aidc-portal` entries in `config.yml` — set independently per VM according to your deployment scale:

| Deployment Scale | Nodes    | CPU     | Memory |
| ---------------- | -------- | ------- | ------ |
| **Small**        | ≤ 50     | 4 cores | 32 GB  |
| **Medium**       | 51 – 500 | 8 cores | 64 GB  |
| **Large**        | 500+     | 8 cores | 128 GB |

### Network

Both VMs get a Management NIC and a Data NIC, each configured with a static IP in `config.yml`:

| VM            | Network    | Recommended Speed | Purpose                                                          |
| ------------- | ---------- | ----------------- | ---------------------------------------------------------------- |
| `aidc-cli`    | Management | 1 GbE             | Internet access / License activation / Administrative operations |
| `aidc-cli`    | Data       | 100 GbE or above  | Node deployment / Rack validation                                |
| `aidc-portal` | Management | 1 GbE             | Internet access / License activation / Administrative operations |
| `aidc-portal` | Data       | 100 GbE or above  | Communication with AIDC-CLI                                      |

Each network maps to a host-side interface (or bridge) defined in `deployment/kvm.yml` — see below.

{% hint style="info" %}
Both VMs' Data networks must be on the **same subnet** so `aidc-cli` and `aidc-portal` can communicate.
{% endhint %}

***

## Deploying with aidc-deploy <a href="#deploying-with-aidc-deploy" id="deploying-with-aidc-deploy"></a>

`aidc-deploy` supports two deployment modes.

### Interactive Mode

Run the tool with no arguments to launch the setup wizard. It loads the default `config.yml`, walks through package, VM, and network parameters, shows a summary, and — once you confirm — saves your answers back into `config.yml` and `deployment/kvm.yml` before starting deployment.

```bash
$ ./aidc-deploy
========================================
       AIDC Deployment Wizard
========================================
Select Deployment Package
  1) AIDC CLI
  2) AIDC Full Stack
Select [1]: 2
========================================
       KVM Configuration
========================================
Select Network Type
  1) macvtap (Default)
  2) bridge
Select [1]: 1
Management Interface [eth0]: eth0
Data Interface [eth1]: eth1
========================================
       AIDC CLI VM
========================================
CPU [4]: 4
Memory (MB) [4096]: 4096
Management IP [192.168.10.10/24]:
Data IP [10.10.10.20/24]:
========================================
       AIDC Portal VM
========================================
CPU [4]: 4
Memory (MB) [4096]: 4096
Management IP [192.168.10.11/24]:
Data IP [10.10.10.21/24]:
========================================
       Management Network
========================================
Gateway [192.168.10.1]:
DNS [8.8.8.8]:
========================================
       Configuration Summary
========================================
Platform: KVM
Deployment Package: AIDC Full Stack
Network Type: macvtap
...
Save configuration and start deployment? [Y/n]: Y
Configuration saved to:
  config.yml
  deployment/kvm.yml
Starting deployment...
```

* Pressing **Enter** accepts the default value shown in brackets.
* Invalid values are rejected with a clear error message.
* Selecting **AIDC CLI** only prompts for the `aidc-cli` VM; selecting **AIDC Full Stack** also prompts for the `aidc-portal` VM.

### Configuration Mode

Once you have a saved `config.yml` and `deployment/kvm.yml`, reuse them without the wizard:

```bash
./aidc-deploy \
  --config config.yml \
  --deployment deployment/kvm.yml
```

This validates the configuration and QCOW2 images, then deploys directly.

### config.yml Reference

`config.yml` defines each VM's hardware and per-VM guest network configuration:

```yaml
vms:
  aidc-cli:
    image: images/aidc-cli.qcow2
    cpu: 4
    memory: 4096
    disk:
      bus: virtio
    networks:
      management:
        model: virtio
        ip:
          address: 192.168.10.10/24
          gateway: 192.168.10.1
          dns:
            - 8.8.8.8
      data:
        model: virtio
        ip:
          address: 10.10.10.20/24
  aidc-portal:
    image: images/aidc-portal.qcow2
    cpu: 4
    memory: 4096
    disk:
      bus: virtio
    networks:
      management:
        model: virtio
        ip:
          address: 192.168.10.11/24
          gateway: 192.168.10.1
          dns:
            - 8.8.8.8
      data:
        model: virtio
        ip:
          address: 10.10.10.21/24
```

To deploy AIDC-CLI only, remove (or ignore) the `aidc-portal` entry — or select **AIDC CLI** in the interactive wizard. Disk bus and network adapter model are fixed to **VirtIO**; duplicate IP addresses across VMs are rejected.

### deployment/kvm.yml Reference

`deployment/kvm.yml` defines the host-side network mapping. Default (macvtap):

```yaml
platform: kvm
kvm:
  connection: qemu:///system
  storage_pool: default
networks:
  management:
    type: macvtap
    interface: eth0
  data:
    type: macvtap
    interface: eth1
```

Each VM gets its own macvtap sub-interface directly off the physical `eth0`/`eth1` — no host-side bridge device is created:

```mermaid
flowchart LR
    subgraph Host
        eth0["eth0"]
        eth1["eth1"]
    end

    subgraph portal["VM: aidc-portal"]
        p_mgmt["mgmt macvtap"]
        p_data["data macvtap"]
    end

    subgraph cli["VM: aidc-cli"]
        c_mgmt["mgmt macvtap"]
        c_data["data macvtap"]
    end

    eth0 -.-> p_mgmt
    eth0 -.-> c_mgmt
    eth1 -.-> p_data
    eth1 -.-> c_data
```

Bridge alternative:

```yaml
platform: kvm
kvm:
  connection: qemu:///system
  storage_pool: default
networks:
  management:
    type: bridge
    bridge: br-mgmt
  data:
    type: bridge
    bridge: br-data
```

`eth0`/`eth1` instead join a host-side Linux bridge (`br-mgmt`/`br-data`), and each VM connects to that bridge through its own tap device:

```mermaid
flowchart LR
    subgraph Host
        eth0["eth0"] --- br_mgmt["br-mgmt"]
        eth1["eth1"] --- br_data["br-data"]
    end

    subgraph portal["VM: aidc-portal"]
        p_mgmt["mgmt tap"]
        p_data["data tap"]
    end

    subgraph cli["VM: aidc-cli"]
        c_mgmt["mgmt tap"]
        c_data["data tap"]
    end

    br_mgmt -.-> p_mgmt
    br_mgmt -.-> c_mgmt
    br_data -.-> p_data
    br_data -.-> c_data
```

{% hint style="warning" %}
Bridge mode requires the host's management and data NICs to be reconfigured as Linux bridges before deployment.
{% endhint %}

### Image Validation

Before creating or modifying any VM, `aidc-deploy` validates every required QCOW2 image: it confirms the image and its `.sha256` file exist, runs `sha256sum -c`, then `qemu-img info` and `qemu-img check`. Deployment aborts — with no VM created or modified — if any check fails.

### Removing a Deployment

`aidc-deploy destroy` stops and removes the VMs defined in your configuration, along with their disks:

```bash
./aidc-deploy destroy \
  --config config.yml \
  --deployment deployment/kvm.yml
```

Running `./aidc-deploy destroy` without flags launches an interactive confirmation instead, listing the VMs to be removed and requiring you to type `DELETE` to proceed. Only VMs defined in your configuration are ever removed.

***

## Accessing AIDC-CLI and AIDC-Portal

### AIDC-CLI (SSH)

```bash
ssh admin@<management_ip>
# Default password: admin
```

Use the Management IP you set for the `aidc-cli` VM in `config.yml`. AIDC-CLI is already installed in the image — verify it with:

```bash
aidc-cli --version
```

{% hint style="warning" %}
Change the default password immediately after deployment for security.
{% endhint %}

### AIDC-Portal (Browser)

**1. Hostname mapping (required).** Add a mapping on your client machine so the Portal's domain name resolves. Update the hosts file on your operating system:

**Linux / macOS** — `/etc/hosts` **Windows** — `C:\Windows\System32\drivers\etc\hosts`

Add the following entry, replacing the IP address with the Management IP you assigned to the `aidc-portal` VM in `config.yml`:

```
192.168.10.11   aidc.asus
```

**2. Open the Portal in your browser.** Navigate to:

```
https://aidc.asus/aidc/portal
```

**Recommended browsers:** Google Chrome, Mozilla Firefox, Microsoft Edge, Safari.

**3. Log in with the default credentials:**

* **Username:** `admin`
* **Password:** `admin`

{% hint style="warning" %}
Change the default password immediately after your first login for security.
{% endhint %}

***

## AIDC-CLI Directory Structure

After deployment, the AIDC-CLI data directory is organized as follows:

```
/home/admin/data/
├── config/         # Configuration files (basic_config, etc.)
├── driver/         # Hardware drivers
│   ├── ofed/       # Mellanox OFED drivers
│   ├── doca/       # NVIDIA DOCA drivers
│   └── gpu/        # NVIDIA GPU drivers
├── firmware/       # Firmware images
│   ├── bios/       # BIOS firmware files
│   ├── bmc/        # BMC firmware files
│   └── mlnx/       # Mellanox NIC/DPU firmware
├── iso/            # OS ISO images
├── node_info/      # Node inventory CSV files
│   └── aidc.csv    # Main node database
├── os_info/        # OS information files
└── report/         # Generated reports
    ├── hardware-spec/
    ├── fw-validation/
    ├── hardware/
    ├── net-conn/
    ├── port-mapping/
    └── system-info/
```

### OS Information File Naming Convention

OS image information files follow the naming pattern: `OS-Version-Platform.yml`

Example files in `data/os_info/`:

* `RHEL-9.6-aarch64.yml`
* `RHEL-9.8-x86_64.yml`
* `Ubuntu-24.04.4-x86_64.yml`
* `Ubuntu-26.04-aarch64.yml`

### CSV File Location

The main node inventory file is located at: `data/node_info/aidc.csv`

***

## Supported Target OS

AIDC-CLI supports deploying the following operating systems on target nodes. See [Init.md §10.6](/guide/latest/cli/commandreference/init.md#deploy-image-management) for the authoritative, up-to-date list read from `os_info/`.

| OS     | Version | Architecture     |
| ------ | ------- | ---------------- |
| RHEL   | 9.6     | aarch64, x86\_64 |
| RHEL   | 9.8     | aarch64, x86\_64 |
| Ubuntu | 24.04.4 | aarch64, x86\_64 |
| Ubuntu | 26.04   | aarch64, x86\_64 |

### Default OS Passwords

| OS     | Username | Password |
| ------ | -------- | -------- |
| RHEL   | root     | password |
| Ubuntu | root     | password |

{% hint style="warning" %}
Change default passwords immediately after deployment for security.
{% endhint %}

***

## AIDC-CLI Post-Installation Setup

### 1. License Activation

All commands except `license` require an active license.

```bash
# Activate with license key
aidc-cli license active -k "XXXX-XXXX-XXXX-XXXX"

# Verify license status
aidc-cli license show
```

### 2. BMC Configuration

Save the BMC credentials once — BMC-based commands (`bmc`, `bios`, `fwupdate`, `hwsensor`, …) read them from here on.

```bash
# View current BMC configuration
aidc-cli init bmc-get

# Set the BMC password and network defaults
aidc-cli init bmc-set -p "YourBMCPassword" -m 255.255.255.0 -g 192.168.2.1
```

### 3. Node Database (CSV Inventory)

AIDC-CLI uses CSV files as node inventory. The CSV file is located at `data/node_info/aidc.csv` and should contain the following columns:

```
index, node_group, serial_number, hostname, model, password, bmc_ip, bmc_mac,
eth0_ip, eth0_mac, eth1_ip, eth2_ip, eth3_ip, bond0_ip, bond1_ip, bond2_ip,
bond3_ip, ib0_ip, ib1_ip, ib2_ip, ib3_ip, ib4_ip, ib5_ip, ib6_ip, ib7_ip,
leaf, spine
```

Then render the inventory:

```bash
aidc-cli init inventory
```

{% hint style="info" %}
The `init inventory` command validates for duplicate IPs and device limits before rendering. Fix any errors in the CSV before proceeding.
{% endhint %}

### 4. DHCP Configuration (For OS Deployment)

```bash
# View current DHCP settings
aidc-cli init dhcp-get

# Configure DHCP
aidc-cli init dhcp-set -s 192.168.1.0 -m 255.255.255.0 -r 192.168.1.1 -n 192.168.1.10 -g 192.168.1.100,192.168.1.200

# Validate CSV IPs against DHCP subnet
aidc-cli init dhcp-validate
```

{% hint style="info" %}
Setup done? Continue with the [Getting Started](/guide/latest/cli/gettingstarted.md) guide for the full deployment walkthrough — from inventory to OS deployment, services, and validation.
{% endhint %}

***

## AIDC-CLI Main Functions

| Category        | Command      | Description                                                         |
| --------------- | ------------ | ------------------------------------------------------------------- |
| Initialization  | `init`       | Node inventory, DHCP, BMC, network, service, and disk configuration |
| License         | `license`    | License activation and management                                   |
| Deployment      | `deploy`     | OS deployment via PXE boot, DHCP and proxy management               |
| BMC             | `bmc`        | BMC/IPMI power control, network, password management                |
| System Config   | `syscfg`     | SSH, NTP, timezone, repositories, RAID, subscription                |
| Network         | `network`    | Apply Ethernet, bonding, InfiniBand, NVOS, link type, DPU mode      |
| Security        | `security`   | Firewall and SELinux management                                     |
| Package         | `pkg`        | Extra package install/remove, NVLink switch OS                      |
| Driver          | `driver`     | OFED, DOCA, GPU driver installation                                 |
| Firmware Update | `fwupdate`   | BIOS, BMC, NIC, DPU, NVMe firmware updates                          |
| Firmware Check  | `chkfw`      | Firmware version validation                                         |
| Hardware Spec   | `hwspec`     | Hardware specification collection                                   |
| Hardware Sensor | `hwsensor`   | Temperature, power, fan sensor monitoring                           |
| Network Check   | `chknet`     | PXE, BMC, InfiniBand, Ethernet port validation                      |
| Slurm           | `slurm`      | Slurm workload manager deployment                                   |
| Kubernetes      | `kubernetes` | Kubernetes cluster deployment                                       |
| Container       | `container`  | Docker and Podman container runtime deployment                      |

***

## Troubleshooting <a href="#troubleshooting-aidc-deploy-failure-common-issues" id="troubleshooting-aidc-deploy-failure-common-issues"></a>

### 1. Deployment host is not Ubuntu 24.04 LTS

**Symptom:** `aidc-deploy` aborts immediately with an unsupported OS/version error.

* `aidc-deploy` only supports Ubuntu 24.04 LTS as the deployment host. Re-run it from a host with that exact OS/version.

### 2. Dependency installation failed

**Symptom:** `aidc-deploy` aborts while installing or verifying required packages (`qemu-img`, `libvirtd`, `virsh`, …).

* Confirm the deployment host has internet/repo access for `apt`.
* Install the missing package manually, then re-run `aidc-deploy`.

### 3. KVM/libvirt not accessible

**Symptom:** `failed to connect to libvirt` or the wizard cannot reach the local KVM service.

```bash
sudo systemctl enable --now libvirtd
sudo systemctl status libvirtd
```

### 4. QCOW2 image validation failed

**Symptom:** `aidc-deploy` aborts during image validation (missing file, checksum mismatch, or `qemu-img check` failure). No VM is created or modified.

* Verify `images/*.qcow2` and their matching `.sha256` files are both present and untouched.
* Re-extract the release package if the checksum does not match.

### 5. Duplicate IP address rejected

**Symptom:** The wizard or configuration validation rejects the same IP used by more than one VM/network.

* Assign a unique Management IP and Data IP to each VM in `config.yml`.

### 6. Permission issue

**Symptom:** Dependency installation or VM management fails with a permissions error.

* Run `aidc-deploy` with `sudo`, or ensure your user has the required `libvirt`/`sudo` access.

### 7. Cannot reach the Portal in the browser

**Symptom:** `https://aidc.asus/aidc/portal` doesn't resolve or times out.

* Confirm the hosts-file entry points to the current Management IP of the `aidc-portal` VM.
* Confirm the AIDC-Portal VM is running (`virsh list --all` on the deployment host).
* Confirm your client machine can reach the Portal's Management network.

***