# Proxmox Backup Server (PBS) 자동 등록 스크립트 기획서

## 📋 프로젝트 개요

### 목적
Proxmox VE 호스트에 PBS(Proxmox Backup Server)를 자동으로 등록하고 백업 작업을 구성하는 스크립트

### 주요 기능
- PBS 서버 자동 감지 및 연결
- 스토리지 구성 자동화
- 백업 작업 스케줄 설정
- 기존 백업 설정 마이그레이션

## 🎯 요구사항

### 필수 요구사항
1. **PBS 서버 정보**
   - PBS 서버 IP/호스트명
   - PBS 사용자 인증 정보 (username@realm)
   - PBS API 토큰 또는 비밀번호
   - Datastore 이름

2. **Proxmox VE 요구사항**
   - Proxmox VE 6.x 이상
   - root 권한
   - pvesm 명령어 사용 가능

3. **네트워크 요구사항**
   - PBS 서버와 통신 가능 (포트 8007)
   - 지문(fingerprint) 자동 획득 가능

## 🔧 기능 상세

### 1. PBS 서버 감지 및 검증
```bash
# PBS 서버 연결 테스트
# API 접근 가능 여부 확인
# 지문(fingerprint) 자동 획득
```

### 2. 스토리지 등록
```bash
# PBS 스토리지를 Proxmox VE에 추가
pvesm add pbs <storage-id> \
    --server <pbs-server> \
    --datastore <datastore-name> \
    --username <username@realm> \
    --password <password> \
    --fingerprint <fingerprint>
```

### 3. 백업 작업 구성
- 일일 백업 스케줄 설정
- VM/CT 선택적 백업
- 보존 정책 설정

### 4. 암호화 설정 (선택사항)
- 백업 암호화 키 생성
- 키 안전한 저장

## 📝 스크립트 구조

```
pbs_auto_registration.sh
├── 1. 환경 체크
│   ├── Proxmox 버전 확인
│   ├── 필수 도구 확인
│   └── root 권한 확인
│
├── 2. PBS 정보 수집
│   ├── 대화형 모드
│   ├── 설정 파일 모드
│   └── 환경 변수 모드
│
├── 3. PBS 연결 검증
│   ├── 네트워크 연결 테스트
│   ├── API 인증 테스트
│   └── Datastore 접근 확인
│
├── 4. 스토리지 구성
│   ├── 기존 스토리지 확인
│   ├── 새 스토리지 추가
│   └── 권한 설정
│
├── 5. 백업 작업 설정
│   ├── 백업 대상 선택
│   ├── 스케줄 설정
│   └── 알림 설정
│
└── 6. 검증 및 완료
    ├── 설정 테스트
    ├── 첫 백업 실행 (선택)
    └── 로그 출력
```

## 🔐 보안 고려사항

### 인증 방식
1. **API 토큰 (권장)**
   - 토큰 ID와 시크릿 사용
   - 제한된 권한 부여 가능
   
2. **패스워드 인증**
   - 임시 사용 후 토큰으로 전환 권장
   - 설정 파일에 평문 저장 금지

### 암호화
- 전송 중 암호화: HTTPS (포트 8007)
- 저장 시 암호화: 선택적 백업 암호화

## 📦 설정 파일 예시

### `/etc/pve/pbs_config.conf`
```ini
# PBS Server Configuration
PBS_SERVER=192.168.1.100
PBS_PORT=8007
PBS_DATASTORE=backup-store
PBS_USERNAME=backup@pbs

# API Token (recommended)
PBS_TOKEN_ID=backup@pbs!automation
PBS_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# Storage Configuration
STORAGE_ID=pbs-backup
STORAGE_CONTENT=backup

# Backup Schedule
BACKUP_SCHEDULE="0 2 * * *"  # 매일 새벽 2시
BACKUP_MODE=snapshot
BACKUP_COMPRESS=zstd

# Retention Policy
KEEP_DAILY=7
KEEP_WEEKLY=4
KEEP_MONTHLY=6
KEEP_YEARLY=1

# Notification
NOTIFY_EMAIL=admin@example.com
NOTIFY_MODE=failure  # always|failure
```

## 🚀 사용 방법

### 기본 실행 (대화형)
```bash
bash pbs_auto_registration.sh
```

### 설정 파일 사용
```bash
bash pbs_auto_registration.sh --config /etc/pve/pbs_config.conf
```

### 자동 모드 (프롬프트 없음)
```bash
bash pbs_auto_registration.sh --auto \
    --server 192.168.1.100 \
    --datastore backup-store \
    --username backup@pbs \
    --token-secret "xxxx"
```

## 🔄 기존 백업 마이그레이션

### 로컬 백업에서 PBS로 전환
1. 기존 백업 목록 확인
2. PBS로 백업 복사 (선택사항)
3. 백업 작업 재구성
4. 기존 로컬 백업 정리

## 📊 모니터링 및 검증

### 백업 상태 확인
```bash
# PBS 스토리지 상태
pvesm status

# 백업 작업 목록
pvesh get /cluster/backup

# 최근 백업 로그
cat /var/log/pve/tasks/active
```

### 헬스 체크
- PBS 연결 상태
- 스토리지 용량
- 백업 성공률
- 보존 정책 준수

## 🛠️ 문제 해결

### 일반적인 문제
1. **연결 실패**
   - 방화벽 규칙 확인
   - PBS 서비스 상태 확인
   - 인증서/지문 문제

2. **권한 오류**
   - PBS 사용자 권한 확인
   - Datastore 접근 권한
   - API 토큰 권한

3. **백업 실패**
   - 스토리지 용량 확인
   - 네트워크 안정성
   - VM/CT 상태 확인

## 📈 향후 개선 사항

1. **다중 PBS 서버 지원**
   - 복제/미러링 설정
   - 로드 밸런싱

2. **고급 백업 정책**
   - VM별 다른 스케줄
   - 조건부 백업
   - 증분 백업 최적화

3. **자동 복구**
   - 백업 검증 자동화
   - 복구 테스트 자동화
   - 재해 복구 계획

4. **통합 관리**
   - 웹 UI 대시보드
   - 중앙 집중식 관리
   - 멀티 클러스터 지원

## 📚 참고 자료

- [Proxmox Backup Server Documentation](https://pbs.proxmox.com/docs/)
- [Proxmox VE Storage Documentation](https://pve.proxmox.com/wiki/Storage)
- [PBS API Reference](https://pbs.proxmox.com/docs/api-viewer/)

## 🔍 테스트 시나리오

### 단위 테스트
1. PBS 서버 연결 테스트
2. 인증 테스트
3. 스토리지 추가/제거 테스트

### 통합 테스트
1. 전체 설정 프로세스
2. 백업 실행 테스트
3. 복구 테스트

### 스트레스 테스트
1. 대용량 VM 백업
2. 동시 다중 백업
3. 네트워크 장애 시나리오

## 📄 라이선스
MIT License

## 👥 기여자
- 프로젝트 관리자
- 개발팀
- 테스트팀