> For the complete documentation index, see [llms.txt](https://ia-cloud.gitbook.io/cloudia-manual/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ia-cloud.gitbook.io/cloudia-manual/administrator/storage/guest-boot-disk-recovery.md).

# 게스트 부팅 디스크 복구 (CEPH)

가상머신이 루트 파일시스템 손상으로 부팅하지 못할 때, 부팅 디스크(RBD)를 컴퓨트 노드에 직접 연결(map)하여 오프라인으로 복구하는 절차입니다. 루트 파일시스템은 마운트되지 않은 상태에서만 검사·복구할 수 있으므로, 손상된 부팅 디스크를 노드에 붙여 점검합니다.

> ⚠️ 주의: 이 절차는 해당 가상머신의 부팅 디스크가 **`CEPH` 스토리지 도메인**에 저장된 경우에만 적용됩니다. `LOCAL`, `GFS2`, `NFS` 도메인에는 해당하지 않습니다. (부팅 디스크 도메인 유형은 `스토리지 > 스토리지 도메인` 에서 확인)

## 적용 상황

* 가상머신이 부팅되지 않고 콘솔(noVNC) 접속이 되지 않는 경우
* 콘솔에서 `dracut`/`emergency` 셸, `XFS ... corruption`, 커널 입출력 오류(EIO) 등이 표시되는 경우
* 주로 노드 페일오버 시 강제 종료 이후 발생합니다.

## 사전 확인 값 (관리자 콘솔)

| 값                | 확인 위치                                     |
| ---------------- | ----------------------------------------- |
| **가상머신 이름**      | `인스턴스 > 인스턴스 상세 > 기본 정보 > 이름`             |
| **가상머신 ID**      | `인스턴스 > 인스턴스 상세 > 기본 정보 > ID`             |
| **물리 머신**(배치 노드) | `인스턴스 > 인스턴스 상세 > 기본 정보 > 물리 머신`          |
| **풀 이름**(pool)   | `스토리지 > 스토리지 도메인 > 목록 > 풀 이름` (`CEPH` 타입) |

> 💡 참고: 부팅 디스크 RBD 이름에는 가상머신 **이름**과 **ID**(`_id_<ID>_`)가 포함되므로, **이름 또는 ID 만으로 조회**할 수 있습니다.

## 복구 절차

명령은 Ceph 명령이 가능한 노드(mon/admin)와 해당 가상머신이 떠 있는 컴퓨트 노드에서 `root` 권한으로 실행합니다.

### 1) 배치 노드 및 중복 기동 확인

동일한 가상머신이 여러 노드에 동시에 떠 있는지(스플릿 브레인) 먼저 확인합니다.

* **(콘솔) 정상 배치 노드 확인**: `인스턴스 상세 > 기본 정보 > 물리 머신` — 이 노드가 가상머신이 정상적으로 떠 있어야 할 곳입니다.
* **(노드) 실제 기동 위치 확인**: 모든 컴퓨트 노드에서 아래를 실행합니다.

```bash
virsh list --all | grep '_id_<ID>_'      # 또는 이름으로:  virsh list --all | grep '<이름>'
```

* `물리 머신` 노드에만 있으면 정상입니다.
* **2개 이상 노드에 떠 있으면 스플릿 브레인**입니다. `물리 머신` 노드의 것이 정상본이고, \*\*그 외 노드의 것이 유령(orphan)\*\*입니다.

### 2) 가상머신 종료 (복구 전 어느 노드에도 떠 있으면 안 됨)

* **(콘솔) 정상 배치본 종료**: 관리 대상 가상머신은 콘솔에서 내려야 상태 정합이 맞습니다. `인스턴스 상세 > 종료` 로 해당 인스턴스를 종료합니다.
* **(노드) 유령 정리**: 배치(`물리 머신`) 노드가 **아닌** 노드에서 직접 정리합니다.

```bash
# 도메인 이름은 1) 조회 결과를 그대로 사용
virsh destroy  '<도메인>'
virsh undefine '<도메인>'      # UEFI/vTPM 가상머신이면 --nvram 추가
```

> ⚠️ 주의: `물리 머신` 노드의 정상본은 노드에서 직접 삭제하지 마십시오. 유령만 정리합니다.

### 3) 부팅 디스크(RBD) 확인

풀에서 해당 가상머신의 부팅 디스크를 찾습니다. 부팅 디스크는 이름이 `_blk` 로 끝납니다.

```bash
rbd ls <풀 이름> | grep -E '_id_<ID>_.*_blk$'    # 또는 이름으로:  rbd ls <풀 이름> | grep -i '<이름>'
```

### 4) 사용 중 여부 확인

연결(map) 전에 아무도 디스크를 사용하고 있지 않아야 합니다. `Watchers: none` 이어야 합니다.

```bash
rbd status <풀 이름>/<부팅 이미지>
```

> ⚠️ 주의: 사용 중(watcher 존재)인데 복구하면 디스크가 다시 손상됩니다. 2) 종료를 반드시 먼저 완료하십시오.

### 5) 디스크 연결 및 파티션 확인

```bash
rbd map <풀 이름>/<부팅 이미지>       # → /dev/rbd0
lsblk -f /dev/rbd0
```

전형적인 파티션 구성은 다음과 같습니다.

| 파티션      | 역할                       | 복구 대상                |
| -------- | ------------------------ | -------------------- |
| `rbd0p1` | BIOS boot (`bios_grub`)  | ❌ 파일시스템 없음 — 손대지 말 것 |
| `rbd0p2` | EFI System (`/boot/efi`) | 필요 시 `fsck.vfat`     |
| `rbd0p3` | `/boot`                  | 필요 시                 |
| `rbd0p4` | **루트(`/`)**              | ✅ 핵심 대상              |

### 6) 파일시스템 복구

게스트 OS 계열에 따라 루트 파일시스템이 다르므로, 계열에 맞는 도구를 사용합니다.

| 게스트 OS 계열           | 루트 파일시스템 | 복구 명령                                          |
| ------------------- | -------- | ---------------------------------------------- |
| **Rocky / RHEL 계열** | XFS      | `xfs_repair /dev/rbd0p4` (막히면 `xfs_repair -L`) |
| **Ubuntu 계열**       | ext4     | `fsck.ext4 -f -y /dev/rbd0p4`                  |

```bash
# Rocky / RHEL 계열 (XFS)
xfs_repair /dev/rbd0p4          # 막히면: xfs_repair -L /dev/rbd0p4

# Ubuntu 계열 (ext4)
fsck.ext4 -f -y /dev/rbd0p4
```

> 💡 참고: OS 계열로 판단하되, 커스텀 이미지 등 확실하지 않으면 `blkid /dev/rbd0p4` 로 실제 유형(`xfs`/`ext4`)을 확인한 뒤 도구를 선택합니다. 💡 참고: 루트 복구 후에도 부팅되지 않으면 `/boot`(p3), EFI(p2)도 같은 방식으로 점검합니다.

### 7) 연결 해제 후 재기동

```bash
rbd unmap /dev/rbd0
```

반드시 연결을 해제한 뒤, 관리자 콘솔에서 해당 가상머신을 기동하고 부팅·콘솔이 정상인지 확인합니다.

## 주의 사항

* 연결(map) 전 반드시 **`Watchers: none`** 을 확인합니다. 노드에 접근할 수 없어 정상 종료가 불가능하면 `ceph osd blocklist add <ip:0/nonce>` 로 해당 사용자만 차단합니다. (IP 전체 차단 금지)
* 스플릿 브레인 정리 시 **`물리 머신` 노드의 정상본은 노드에서 삭제하지 않습니다.** 유령만 정리합니다.
* `rbd0p1`(bios\_grub)에는 복구 명령을 실행하지 않습니다.
* 복구 후에는 반드시 **`rbd unmap` → 재기동** 순서를 지킵니다. (해제 없이 기동하면 다시 손상됩니다.)