# Tailscale TUN 디바이스 설정 성공 보고서

**작성일시**: 2025-11-02 17:21 KST
**대상 컨테이너**: Ubuntu24 LXC (VMID 101)
**작업 목적**: LXC 컨테이너에서 Tailscale 실행을 위한 TUN 디바이스 설정

---

## 문제 상황

### 초기 증상
- Tailscale 데몬(tailscaled.service) 실행 실패
- 상태: `failed (Result: exit-code)`
- 재시작 시도 5회 후 중단

### 원인 분석
```
Nov 02 16:22:09 Ubuntu24 tailscaled[299184]: wgengine.NewUserspaceEngine(tun "tailscale0") error:
tstun.New("tailscale0"): CreateTUN("tailscale0") failed; /dev/net/tun does not exist
```

**핵심 문제**: LXC 컨테이너 내부에 `/dev/net/tun` 디바이스가 존재하지 않음

### 기술적 배경
- Tailscale은 VPN 터널링을 위해 TUN 네트워크 디바이스가 필요
- LXC 컨테이너는 기본적으로 보안을 위해 디바이스 접근을 제한
- TUN 디바이스는 문자 디바이스(character device) `c 10:200`

---

## 해결 과정

### 1. 사전 백업
```bash
# 스냅샷 생성
pct snapshot 101 tailscale_fix_before -description "Tailscale TUN 설정 전 백업 - 2025-11-02 17:16"

# 설정 파일 백업
cp /etc/pve/lxc/101.conf /etc/pve/lxc/101.conf.backup
```

**백업 항목**:
- LXC 전체 시스템 스냅샷
- 설정 파일 백업
- 실행 중인 서비스 상태 리포트 작성

### 2. 컨테이너 중지
```bash
pct stop 101
```

**영향받은 서비스**:
- code-server (포트 8680, 8080)
- gp9.service (약국 크롤링)
- prescription-monitoring.service (처방전 모니터링)
- mosquitto (MQTT 브로커)
- samba (파일 공유)

### 3. LXC 설정 파일 수정

**수정 파일**: `/etc/pve/lxc/101.conf`

**추가된 설정**:
```conf
lxc.cgroup2.devices.allow: c 10:200 rwm
lxc.mount.entry: /dev/net dev/net none bind,create=dir
```

**설정 설명**:
- `lxc.cgroup2.devices.allow: c 10:200 rwm`
  - cgroup2를 통해 문자 디바이스 10:200 (TUN) 접근 허용
  - rwm = read, write, mknod 권한

- `lxc.mount.entry: /dev/net dev/net none bind,create=dir`
  - 호스트의 `/dev/net` 디렉토리를 컨테이너에 바인드 마운트
  - `create=dir`: 디렉토리가 없으면 자동 생성

**설정 위치**: 메인 컨테이너 설정 블록 끝 (unprivileged: 0 다음)

### 4. 컨테이너 재시작
```bash
pct start 101
```

**재시작 완료**: 약 5초 소요

### 5. TUN 디바이스 확인
```bash
pct exec 101 -- ls -la /dev/net/tun
```

**결과**:
```
crw-rw-rw- 1 root root 10, 200 Sep 18 22:34 /dev/net/tun
```
✅ TUN 디바이스 정상 생성 확인

### 6. Tailscale 서비스 시작
```bash
pct exec 101 -- systemctl start tailscaled
pct exec 101 -- systemctl status tailscaled
```

**결과**:
```
● tailscaled.service - Tailscale node agent
     Loaded: loaded (/usr/lib/systemd/system/tailscaled.service; enabled; preset: enabled)
     Active: active (running) since Sun 2025-11-02 17:20:55 KST
   Main PID: 256 (tailscaled)
     Status: "Needs login: "
      Tasks: 11
     Memory: 50.7M
        CPU: 602ms
```
✅ Tailscale 데몬 정상 실행 확인

---

## 최종 결과

### 성공 확인
- TUN 디바이스: **정상 작동** (`/dev/net/tun` 존재)
- Tailscale 데몬: **active (running)**
- 서비스 상태: "Needs login" (정상 - 로그인 대기 상태)
- 에러 로그: **없음**

### 추가 작업 필요
Tailscale 네트워크 연결을 위해 로그인 필요:
```bash
pct exec 101 -- tailscale up
```
위 명령 실행 후 제공되는 인증 URL로 접속하여 Tailscale 계정 인증

---

## 기술 요약

### 적용된 LXC 설정
| 설정 항목 | 값 | 용도 |
|----------|-----|------|
| lxc.cgroup2.devices.allow | c 10:200 rwm | TUN 디바이스 접근 권한 |
| lxc.mount.entry | /dev/net dev/net none bind,create=dir | TUN 디바이스 마운트 |

### 디바이스 정보
- **디바이스 타입**: Character device
- **Major number**: 10
- **Minor number**: 200
- **권한**: crw-rw-rw- (읽기/쓰기)
- **경로**: /dev/net/tun

---

## 복원 방법

문제 발생 시 이전 상태로 복원:

### 방법 1: 스냅샷 복원
```bash
pct rollback 101 tailscale_fix_before
pct start 101
```

### 방법 2: 설정 파일 복원
```bash
pct stop 101
cp /etc/pve/lxc/101.conf.backup /etc/pve/lxc/101.conf
pct start 101
```

---

## 참고 자료

### LXC에서 Tailscale 실행하기
- Proxmox LXC는 기본적으로 보안을 위해 장치 접근 제한
- VPN 솔루션(Tailscale, WireGuard 등)은 TUN/TAP 디바이스 필요
- unprivileged 컨테이너에서는 추가 설정 필요할 수 있음

### 관련 문서
- Tailscale 공식 문서: https://tailscale.com/kb/
- Proxmox LXC 문서: https://pve.proxmox.com/wiki/Linux_Container
- Linux TUN/TAP: https://www.kernel.org/doc/Documentation/networking/tuntap.txt

---

## 작업 이력

| 시간 | 작업 내용 | 상태 |
|------|-----------|------|
| 17:16 | 스냅샷 생성 (tailscale_fix_before) | ✅ 완료 |
| 17:16 | 리포트 작성 (Ubuntu24_LXC_Status_Report.md) | ✅ 완료 |
| 17:17 | LXC 컨테이너 중지 | ✅ 완료 |
| 17:18 | TUN 디바이스 설정 추가 | ✅ 완료 |
| 17:19 | LXC 컨테이너 시작 | ✅ 완료 |
| 17:20 | TUN 디바이스 확인 | ✅ 정상 |
| 17:20 | Tailscale 서비스 시작 | ✅ 정상 |
| 17:21 | Tailscale 상태 확인 | ✅ 정상 |

---

## 결론

LXC 컨테이너에서 Tailscale을 실행하기 위해 필요한 TUN 디바이스 설정을 성공적으로 완료했습니다.

**주요 성과**:
1. ✅ TUN 디바이스 접근 권한 설정
2. ✅ Tailscale 데몬 정상 실행
3. ✅ 모든 기존 서비스 정상 작동
4. ✅ 백업 및 복원 방법 확보

**다음 단계**: Tailscale 계정 인증 후 네트워크 연결

---

**작성자**: Claude Code
**문서 버전**: 1.0
**최종 수정**: 2025-11-02 17:21 KST