pve-add-pbs-storage/README.md

# Proxmox VE - PBS Storage 자동 추가 스크립트

Proxmox Backup Server(PBS)를 Proxmox VE의 스토리지로 쉽고 빠르게 추가하는 스크립트입니다.

## 특징

- ✅ 대화형 모드로 쉬운 설정
- ✅ 비대화형 모드로 자동화 가능
- ✅ API Token 및 사용자명/비밀번호 인증 지원
- ✅ SSL 핑거프린트 검증 지원
- ✅ 자동 연결 테스트
- ✅ 상세한 에러 메시지

## 요구사항

- Proxmox VE 7.0 이상
- PBS (Proxmox Backup Server) 설치 및 실행 중
- PBS에서 생성된 API Token 또는 사용자 계정
- Root 권한

## 빠른 설치

### 방법 1: 원라인 설치 (대화형 모드)

```bash
curl -fsSL https://git.0bin.in/thug0bin/pve-add-pbs-storage/raw/branch/main/add-pbs-storage.sh | bash
```

### 방법 2: 다운로드 후 실행

```bash
wget https://git.0bin.in/thug0bin/pve-add-pbs-storage/raw/branch/main/add-pbs-storage.sh
chmod +x add-pbs-storage.sh
./add-pbs-storage.sh
```

## 사용 방법

### 1. 대화형 모드 (권장)

스크립트를 실행하면 대화형으로 필요한 정보를 입력받습니다:

```bash
./add-pbs-storage.sh
```

입력할 정보:
- 스토리지 ID (예: `pbs-backup`)
- PBS 서버 주소 (IP 또는 도메인)
- 데이터스토어 이름 (기본값: `datastore1`)
- 인증 방법 (API Token 또는 사용자명/비밀번호)
- 포트 (기본값: `8007`)
- SSL 핑거프린트 (선택사항)

### 2. 비대화형 모드 (자동화)

#### API Token 사용 (권장)

```bash
./add-pbs-storage.sh \
  -i "pbs-backup" \
  -s "192.168.1.100" \
  -d "datastore1" \
  -t "root@pam!backup" \
  -T "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

#### 사용자명/비밀번호 사용

```bash
./add-pbs-storage.sh \
  -i "pbs-backup" \
  -s "pbs.example.com" \
  -d "datastore1" \
  -u "root@pam" \
  -p "your-password"
```

#### 전체 옵션 사용 예시

```bash
./add-pbs-storage.sh \
  -i "pbs-backup" \
  -s "192.168.1.100" \
  -d "datastore1" \
  -t "root@pam!backup" \
  -T "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  -P 8007 \
  -m 3 \
  -c "backup" \
  -f "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:25:26:27:28:29:30:31:32"
```

## 명령어 옵션

### 필수 옵션

| 옵션 | 설명 | 예시 |
|------|------|------|
| `-i` | 스토리지 ID | `pbs-backup` |
| `-s` | PBS 서버 주소 | `192.168.1.100` 또는 `pbs.example.com` |
| `-d` | 데이터스토어 이름 | `datastore1` |

### 인증 옵션 (둘 중 하나 필수)

**API Token (권장):**

| 옵션 | 설명 | 예시 |
|------|------|------|
| `-t` | API Token Name | `root@pam!backup` |
| `-T` | API Token Secret | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |

**사용자명/비밀번호:**

| 옵션 | 설명 | 예시 |
|------|------|------|
| `-u` | 사용자명 | `root@pam` |
| `-p` | 비밀번호 | `your-password` |

### 추가 옵션

| 옵션 | 설명 | 기본값 |
|------|------|--------|
| `-P` | PBS 포트 | `8007` |
| `-f` | SSL Fingerprint | 없음 |
| `-m` | 최대 백업 파일 수 | `1` |
| `-c` | 컨텐츠 타입 | `backup` |
| `-h` | 도움말 표시 | - |

## PBS API Token 생성 방법

PBS 웹 인터페이스에서 API Token을 생성하는 방법:

1. PBS 웹 UI 접속: `https://PBS_IP:8007`
2. **Configuration** → **Access Control** → **API Tokens**
3. **Add** 버튼 클릭
4. 다음 정보 입력:
   - User: `root@pam`
   - Token Name: `backup` (원하는 이름)
5. **Add** 클릭
6. 생성된 **Secret**을 복사 (한 번만 표시됨!)

생성된 토큰 형식:
- Token Name: `root@pam!backup`
- Token Secret: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`

## SSL Fingerprint 확인 방법

PBS 서버의 SSL 핑거프린트를 확인하려면:

```bash
# PBS 서버에서 실행
openssl x509 -in /etc/proxmox-backup/proxy.pem -noout -fingerprint -sha256
```

또는 PVE에서 확인:

```bash
openssl s_client -connect PBS_IP:8007 < /dev/null 2>/dev/null | \
  openssl x509 -noout -fingerprint -sha256 | \
  cut -d= -f2
```

## 예시 시나리오

### 시나리오 1: 로컬 네트워크 PBS 추가

```bash
./add-pbs-storage.sh \
  -i "local-pbs" \
  -s "192.168.1.50" \
  -d "backups" \
  -t "root@pam!backup-token" \
  -T "12345678-1234-1234-1234-123456789abc"
```

### 시나리오 2: 원격 PBS 추가 (핑거프린트 검증)

```bash
./add-pbs-storage.sh \
  -i "remote-pbs" \
  -s "pbs.company.com" \
  -d "datastore1" \
  -t "backup@pbs!remote" \
  -T "87654321-4321-4321-4321-cba987654321" \
  -f "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:25:26:27:28:29:30:31:32"
```

### 시나리오 3: 다중 백업 보관

```bash
./add-pbs-storage.sh \
  -i "pbs-longterm" \
  -s "192.168.1.100" \
  -d "longterm-storage" \
  -t "root@pam!backup" \
  -T "your-token-secret" \
  -m 10
```

## 스토리지 확인

스크립트 실행 후 다음 명령어로 스토리지를 확인할 수 있습니다:

```bash
# 모든 스토리지 목록 보기
pvesm status

# 특정 스토리지 상태 확인
pvesm status -storage pbs-backup

# 스토리지 설정 보기
cat /etc/pve/storage.cfg
```

## 스토리지 제거

PBS 스토리지를 제거하려면:

```bash
pvesm remove pbs-backup
```

## 백업 생성 방법

PBS 스토리지를 추가한 후 백업을 생성하는 방법:

### 웹 UI에서:
1. VM 또는 Container 선택
2. **Backup** 탭 클릭
3. **Backup now** 버튼 클릭
4. Storage: PBS 스토리지 선택
5. **Backup** 클릭

### 명령줄에서:
```bash
# VM 백업
vzdump 100 --storage pbs-backup --mode snapshot

# 여러 VM 백업
vzdump 100 101 102 --storage pbs-backup --mode snapshot

# Container 백업
vzdump 200 --storage pbs-backup
```

## 자동 백업 스케줄 설정

웹 UI에서 자동 백업 스케줄 설정:

1. **Datacenter** → **Backup**
2. **Add** 버튼 클릭
3. 다음 설정:
   - Storage: PBS 스토리지 선택
   - Schedule: 백업 주기 설정 (예: `0 2 * * *` = 매일 새벽 2시)
   - Selection Mode: VM 선택 방식
   - Retention: 보관 정책

## 문제 해결

### 연결 실패

```bash
# PBS 서버 연결 확인
ping PBS_IP

# PBS 포트 확인
nc -zv PBS_IP 8007

# PBS 서비스 상태 확인 (PBS 서버에서)
systemctl status proxmox-backup-proxy
```

### 인증 실패

- API Token이 올바른지 확인
- Token에 필요한 권한이 있는지 확인 (PBS에서 확인)
- 사용자명 형식 확인: `username@realm` (예: `root@pam`)

### SSL 인증서 오류

- 자체 서명 인증서를 사용하는 경우 핑거프린트를 지정하세요
- 또는 PBS에 유효한 인증서를 설치하세요

### 데이터스토어를 찾을 수 없음

PBS 웹 UI에서 데이터스토어가 생성되어 있는지 확인:
- PBS UI → **Datastore** 확인

## 고급 설정

### 컨텐츠 타입

지원되는 컨텐츠 타입:
- `backup`: VM 및 Container 백업 (기본값)
- `snippets`: 스니펫 파일

여러 타입 지정:
```bash
-c "backup,snippets"
```

### 보존 정책

최대 백업 파일 수 설정:
```bash
-m 5  # 최근 5개 백업만 보관
```

## 보안 권장사항

1. ✅ API Token 사용 (비밀번호보다 안전)
2. ✅ Token에 최소 권한만 부여
3. ✅ SSL 핑거프린트 검증 사용
4. ✅ 방화벽에서 PBS 포트(8007) 제한
5. ✅ 정기적으로 Token 갱신

## 자주 묻는 질문 (FAQ)

### Q: PBS와 NFS/CIFS 백업의 차이는?

**PBS 장점:**
- 중복 제거 (Deduplication)
- 압축
- 암호화
- 백업 검증
- 증분 백업

### Q: 여러 PVE 노드에서 같은 PBS 사용 가능?

네, 각 PVE 노드에서 이 스크립트를 실행하면 됩니다.

### Q: PBS 백업을 외부로 복제하려면?

PBS에서 **Remote** 및 **Sync Jobs**를 설정하세요.

## 참고 자료

- [Proxmox Backup Server 공식 문서](https://pbs.proxmox.com/docs/)
- [Proxmox VE Storage 설정](https://pve.proxmox.com/wiki/Storage)
- [PBS API 문서](https://pbs.proxmox.com/docs/api-viewer/)

## 라이선스

MIT License

## 기여

Issues 및 Pull Requests는 언제나 환영합니다!

## 관련 프로젝트

- [pve9-repo-fix](https://git.0bin.in/thug0bin/pve9-repo-fix) - Proxmox VE 9.0 저장소 수정 스크립트