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

# Installation & Setup

| Developer | Last modified |
| --------- | ------------- |
| AIDC Team | 2026/02/12    |

## Overview

AIDC-CLI (ASUS Infrastructure Deployment Center-CLI) provides a stable and consistent configuration for automating and managing nodes efficiently. The CLI is deployed inside a Vagrant-managed VM (Libvirt provider) on a management host.

***

## Prerequisites

### 1. Install Development Tools and Required Packages (Example for RHEL)

Before provisioning the AIDC-CLI VM, ensure the following software packages are installed on your host system:

```bash
sudo dnf groupinstall "Development Tools" -y

# Required only on Rocky Linux
sudo dnf group install -y "virtualization hypervisor"
sudo dnf group install -y "virtualization tools"
sudo dnf config-manager --set-enabled crb

sudo dnf install -y qemu-kvm qemu-img virt-manager libvirt libvirt-client libvirt-devel virt-install ruby ruby-devel yum-utils
sudo systemctl enable --now libvirtd
sudo systemctl start libvirtd

sudo systemctl stop firewalld
sudo systemctl disable firewalld
```

### 1.5 Pre-check (One-click Environment Check)

Before running `vagrant up`, ensure the host environment is properly installed and running. You can use the following one-click script to verify the environment:

```bash
#!/bin/bash

echo "==== Check libvirt status ===="
sudo systemctl is-active --quiet libvirtd && echo "libvirtd: active" || echo "libvirtd: inactive"

echo "==== Check KVM modules ===="
lsmod | grep -E "kvm|kvm_intel|kvm_amd" >/dev/null && echo "KVM modules: loaded" || echo "KVM modules: not loaded"

echo "==== Check libvirt network ===="
virsh net-list --all

echo "==== Check vagrant-libvirt plugin ===="
vagrant plugin list | grep -q libvirt && echo "vagrant-libvirt: installed" || echo "vagrant-libvirt: not installed"

echo "==== Check Vagrant version ===="
vagrant --version
```

### 2. Add HashiCorp's Official Repository and Install Vagrant (Example for RHEL)

```bash
# Install Vagrant (ensure version is after 2.3.0 stable)
sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo
sudo yum install vagrant
sudo vagrant plugin install vagrant-libvirt
```

### 3. Obtain and Import the AIDC-CLI Box File

There are **two methods** to obtain the box file:

**Method 1: Download via `wget`**

```bash
wget <release_path>/aidc-cli.box
```

**Method 2: Manual placement** Extract the `aidc-cli.box` file from the release package and place it in the same directory as the Vagrantfile.

Then import the box:

```bash
# Remove existing box if present
vagrant box remove aidc-cli

# Import the box
vagrant box add aidc-cli aidc-cli.box
```

***

## System Requirements

### AIDC Server Node (VM Resources)

**Host OS:**

* RHEL 8.8 (x86\_64)
* Rocky Linux 8.10 (x86\_64)

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

**Network (fixed for all scales):**

| NIC              | Speed            | Purpose                              |
| ---------------- | ---------------- | ------------------------------------ |
| Interconnect NIC | 1 GbE            | Internet access / License activation |
| Provisioning NIC | 100 GbE or above | Node deployment / Rack validation    |

### Vagrantfile Configuration

```ruby
Vagrant.configure("2") do |config|
    # Define network variables
    internal_ip      = "10.10.50.100"
    netmask_internal = "255.255.255.0"
    external_ip      = "192.168.1.101"
    netmask_external = "255.255.255.0"

    # Interconnect network (internet access)
    aidc_cli.vm.network "public_network", ip: external_ip, netmask: netmask_external, dev: "enp3s0"

    # Provisioning network (node deployment / rack validation)
    aidc_cli.vm.network "public_network", ip: internal_ip, netmask: netmask_internal, dev: "enp111s0f0np0"

    # Libvirt provider configuration
    aidc_cli.vm.provider :libvirt do |v, override|
      v.memory = 16384
      v.cpus = 4
      v.connect_via_ssh = false
    end
  end
end
```

### Resource Specifications

Modify the Vagrantfile provider section to adjust resources:

```ruby
v.memory = 16384
v.cpus = 4
```

***

## Usage - Initialize Environment

### Start the VM

```bash
sudo vagrant up
```

### Access the VM

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

Set VM and network to autostart:

```bash
virsh autostart aidc-cli
virsh net-autostart vagrant-libvirt
```

***

## Install AIDC-CLI

### RPM Package

```bash
# Install from the release package (RHEL / Rocky Linux)
sudo dnf install -y ./aidc-cli-<version>.rpm

# Verify installation
aidc-cli --version
```

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

***

## Directory Structure

After installation, 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_8.9_x86_64.yml`
* `RHEL_9.6_aarch64.yml`
* `Ubuntu_22.04.5_x86_64.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:

| OS          | Version | Architecture     |
| ----------- | ------- | ---------------- |
| RHEL        | 8.9     | x86\_64          |
| RHEL        | 9.4     | aarch64          |
| RHEL        | 9.6     | aarch64, x86\_64 |
| Rocky Linux | 8.10    | x86\_64          |
| Ubuntu      | 22.04.5 | x86\_64          |

### Default OS Passwords

| OS                 | Username | Password        |
| ------------------ | -------- | --------------- |
| RHEL / Rocky Linux | root     | password        |
| Ubuntu             | —        | root / password |

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

***

## 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
```

### 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
```

***

## 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 (vagrant up Failure Common Issues)

### 1. `libvirtd` not running or failed

**Symptom:** `failed to connect to libvirt` or `libvirtd is not running`

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

### 2. KVM modules not loaded

**Symptom:** `kvm` related modules not found or VM fails to start

```bash
sudo modprobe kvm
```

### 3. `vagrant-libvirt` plugin missing or incompatible

**Symptom:** `provider 'libvirt' not found`

```bash
vagrant plugin install vagrant-libvirt
```

### 4. Network bridge not defined or IP conflict

**Symptom:** `vagrant up` stuck on network or IP assignment failure

* Verify the interface names in the Vagrantfile.
* Confirm assigned IPs do not conflict with host IPs.
* Check interface availability using `ip a` or `nmcli`.

### 5. Permission issue (mixing sudo and non-sudo)

**Symptom:** Using `sudo vagrant up` once and then `vagrant up` fails

```bash
sudo rm -rf .vagrant
vagrant up
```

### 6. Box file corrupted or download failed

**Symptom:** `box add` fails or `vagrant up` cannot load the box

* Re-download the box file
* Verify file integrity (e.g., MD5 checksum)