driveAtlas/README.md

# Drive Atlas

A powerful server drive mapping tool that generates visual ASCII representations of server layouts and provides comprehensive drive information. Maps physical drive bays to logical Linux device names using PCI bus paths for reliable, persistent identification.

## Features

- Visual ASCII art maps showing physical drive bay layouts
- Persistent drive identification using PCI paths (not device letters)
- SMART health status and temperature monitoring
- Support for SATA, NVMe, and USB drives
- Detailed drive information including model, size, and health status
- Per-server configuration for accurate physical-to-logical mapping

## Quick Start

Execute remotely using curl:
```bash
bash <(curl -s http://10.10.10.63:3000/LotusGuild/driveAtlas/raw/branch/main/driveAtlas.sh)
```

Or using wget:
```bash
bash <(wget -qO- http://10.10.10.63:3000/LotusGuild/driveAtlas/raw/branch/main/driveAtlas.sh)
```

## Requirements

- Linux environment with bash
- `sudo` privileges for SMART operations
- `smartctl` (from smartmontools package)
- `lsblk` and `lspci` (typically pre-installed)
- Optional: `nvme-cli` for NVMe drives

## Server Configurations

### Chassis Types

| Chassis Type | Description | Servers Using It |
|-------------|-------------|------------------|
| **10-Bay Hot-swap** | Sliger CX471225 4U 10x 3.5" NAS (with unused 2x 5.25" bays) | compute-storage-01, storage-01 | compute-storage-gpu-01
| **Spare 10-Bay** | Some random chinese chassis |
| **Large1 Grid** | Unique 3x5 grid layout (1/1 configuration) | large1 |
| **Micro** | Compact 2-drive layout | micro1, monitor-02 |

### Server Details

#### compute-storage-01 (formerly medium2)
- **Chassis:** Sliger CX471225 4U (10-Bay Hot-swap)
- **Motherboard:** B650D4U3-2Q/BCM
- **Controllers:**
  - 0c:00.0 - Front hot-swap bays
  - 0d:00.0 - M.2 NVMe slot
  - 0b:00.0 - USB controller
- **Status:** Partially mapped (bays 3-6 only)

#### storage-01
- **Chassis:** Sliger CX471225 4U (10-Bay Hot-swap)
- **Motherboard:** Different from compute-storage-01
- **Controllers:** Motherboard SATA only (no HBA currently)
- **Status:** Requires PCI path mapping

#### large1
- **Chassis:** Unique 3x5 grid (15 bays total)
- **Note:** 1/1 configuration, will not be replicated
- **Status:** Requires PCI path mapping

#### compute-storage-gpu-01
- **Chassis:** Sliger CX471225 4U (spare, not deployed)
- **Status:** Not currently in use

## How It Works

### PCI Path-Based Mapping

Drive Atlas uses `/dev/disk/by-path/` to create persistent mappings between physical drive bays and Linux device names. This is superior to using device letters (sda, sdb, etc.) which can change between boots.

**Example PCI path:**
```
pci-0000:0c:00.0-ata-1 → /dev/sda
```

This tells us:
- `0000:0c:00.0` - PCI bus address of the storage controller
- `ata-1` - Port 1 on that controller
- Maps to physical bay 3 on compute-storage-01

### Configuration

Server mappings are defined in the `SERVER_MAPPINGS` associative array in [driveAtlas.sh](driveAtlas.sh):

```bash
declare -A SERVER_MAPPINGS=(
    ["compute-storage-01"]="
        pci-0000:0c:00.0-ata-1 3
        pci-0000:0c:00.0-ata-2 4
        pci-0000:0d:00.0-nvme-1 m2-1
    "
)
```

## Setting Up a New Server

### Step 1: Run Diagnostic Script

First, gather PCI path information:

```bash
bash diagnose-drives.sh > server-diagnostic.txt
```

This will show all available PCI paths and their associated drives.

### Step 2: Physical Bay Identification

For each populated drive bay:

1. Note the physical bay number (labeled on chassis)
2. Identify a unique characteristic (size, model, or serial number)
3. Match it to the PCI path from the diagnostic output

**Pro tip:** If uncertain, remove one drive at a time and re-run the diagnostic to see which PCI path disappears.

### Step 3: Create Mapping

Add a new entry to `SERVER_MAPPINGS` in [driveAtlas.sh](driveAtlas.sh):

```bash
["your-hostname"]="
    pci-0000:XX:XX.X-ata-1 1
    pci-0000:XX:XX.X-ata-2 2
    # ... etc
"
```

Also add the chassis type to `CHASSIS_TYPES`:

```bash
["your-hostname"]="10bay"
```

### Step 4: Test

Run the main script and verify the layout matches your physical configuration:

```bash
bash driveAtlas.sh
```

Use debug mode to see the mappings:

```bash
DEBUG=1 bash driveAtlas.sh
```

## Output Example

```
┌──────────────────────────────────────────────────────────────┐
│  compute-storage-01                                          │
│  10-Bay Hot-swap Chassis                                     │
│                                                              │
│    M.2 NVMe Slot                                             │
│    ┌──────────┐                                             │
│    │ nvme0n1  │                                             │
│    └──────────┘                                             │
│                                                              │
│    Front Hot-swap Bays                                       │
│ ┌──────────┐┌──────────┐┌──────────┐┌──────────┐...        │
│ │1: EMPTY  ││2: EMPTY  ││3: sda    ││4: sdb    │...        │
│ └──────────┘└──────────┘└──────────┘└──────────┘...        │
└──────────────────────────────────────────────────────────────┘

=== Drive Details with SMART Status ===
DEVICE          SIZE       TYPE     TEMP     HEALTH   MODEL
--------------------------------------------------------------------------------
/dev/sda        2TB        HDD      35°C     ✓        WD20EFRX-68EUZN0
/dev/nvme0n1    1TB        SSD      42°C     ✓        Samsung 980 PRO
```

## Troubleshooting

### Drive shows as EMPTY but is physically present

- Check if the drive is detected: `ls -la /dev/disk/by-path/`
- Verify the PCI path in the mapping matches the actual path
- Ensure the drive has power and SATA/power connections are secure

### PCI paths don't match between servers with "identical" hardware

- Even identical motherboards can have different PCI addressing
- BIOS settings can affect PCI enumeration
- HBA installation in different PCIe slots changes addresses
- Cable routing to different SATA ports changes the ata-N number

### SMART data not showing

- Ensure `smartmontools` is installed: `sudo apt install smartmontools`
- Some drives don't report temperature
- USB-connected drives may not support SMART
- Run `sudo smartctl -i /dev/sdX` manually to check

## Files

- [driveAtlas.sh](driveAtlas.sh) - Main script
- [diagnose-drives.sh](diagnose-drives.sh) - PCI path diagnostic tool
- [README.md](README.md) - This file
- [todo.txt](todo.txt) - Development notes

## Contributing

When adding support for a new server:

1. Run `diagnose-drives.sh` and save output
2. Physically label or identify drives
3. Create mapping in `SERVER_MAPPINGS`
4. Test thoroughly
5. Document any unique hardware configurations
6. Update this README

## Technical Notes

### Why PCI Paths?

Linux device names (sda, sdb, etc.) are assigned in discovery order, which can change:
- Between kernel versions
- After BIOS updates
- When drives are added/removed
- Due to timing variations at boot

PCI paths are deterministic and based on physical hardware topology.

### Bay Numbering Conventions

- **10-bay chassis:** Bays numbered 1-10 (left to right, top to bottom)
- **M.2 slots:** Labeled as `m2-1`, `m2-2`, etc.
- **USB drives:** Labeled as `usb1`, `usb2`, etc.
- **Large1:** Grid numbering 1-9 (3x3 displayed, additional bays documented in mapping)

## License

Internal tool for LotusGuild infrastructure.