---
title: "Linux에서 OverlayFS를 활용한 고급 파일 시스템 관리 마스터하기"
description: "OverlayFS는 Linux 커널의 유니온 파일 시스템으로, 여러 파일 시스템을 통합된 뷰로 마운트할 수 있게 해줍니다. 기본 사용법으로는 디렉토리 구조 생성, OverlayFS 마운트, 통합 뷰 확인 등이 있으며, 여러 lower 레이어를 지원하고 읽기 전용 마운트도 가능합니다. 성능 테스트와 unionfs-fuse와의 비교를 통해 OverlayFS의 장점이 강조되며, 커널 레벨 구현으로 빠른 성능과 안정성을 제공합니다."
date: "2026-01-19"
last_modified: "2026-05-15T08:36:00.000Z"
type: "Post"
tags:
  - "docker"
  - "ubuntu"
  - "install"
categories:
  - "🤖 Computer Science"
canonical_url: "https://blog.pieroot.xyz/overlayfs-master"
markdown_url: "https://blog.pieroot.xyz/overlayfs-master.md"
---

# Linux에서 OverlayFS를 활용한 고급 파일 시스템 관리 마스터하기

OverlayFS는 Linux 커널의 유니온 파일 시스템으로, 여러 파일 시스템을 통합된 뷰로 마운트할 수 있게 해줍니다. 기본 사용법으로는 디렉토리 구조 생성, OverlayFS 마운트, 통합 뷰 확인 등이 있으며, 여러 lower 레이어를 지원하고 읽기 전용 마운트도 가능합니다. 성능 테스트와 unionfs-fuse와의 비교를 통해 OverlayFS의 장점이 강조되며, 커널 레벨 구현으로 빠른 성능과 안정성을 제공합니다.

## OverlayFS 실습 및 시연 가이드

### OverlayFS란?

OverlayFS는 Linux 커널에 내장된 유니온 파일 시스템입니다. 여러 파일 시스템을 하나의 통합된 뷰로 마운트할 수 있게 해주며, Docker와 같은 컨테이너 기술에서 레이어드 파일 시스템을 구현하는 데 사용됩니다.

기존의 `unionfs-fuse`와 달리 **커널 레벨에서 동작**하기 때문에 성능이 훨씬 뛰어나고, 별도의 설치 없이 대부분의 최신 Linux 배포판에서 바로 사용할 수 있습니다. 🚀

### 설치 확인

#### Ubuntu에서 확인

OverlayFS는 Linux 커널 3.18 이상에서 기본 지원됩니다.

```bash
# 커널 버전 확인
uname -r

# overlay 모듈 확인
lsmod | grep overlay

# 모듈이 로드되어 있지 않다면 로드
sudo modprobe overlay
```

### 기본 사용법

#### 1. 테스트 디렉토리 구조 생성

먼저 실습을 위한 디렉토리를 만들어봅시다.

```bash
# 작업 디렉토리 생성
mkdir -p ~/overlay-demo
cd ~/overlay-demo

# OverlayFS에 필요한 디렉토리 생성
mkdir lower upper work merged

# lower 디렉토리에 파일 생성 (읽기 전용 레이어)
echo "This is from lower layer" > lower/file1.txt
echo "Lower shared file" > lower/shared.txt

# upper 디렉토리에 파일 생성 (읽기/쓰기 레이어)
echo "This is from upper layer" > upper/file2.txt
echo "Upper shared file" > upper/shared.txt
```

![image](https://blog.pieroot.xyz/api/image-proxy?id=b2dfbbad-9c38-4264-94c4-60eb4be0c6e4&kind=s3&pageId=2ed067c0-15d0-8057-9d87-fe09ee46435a&source=block&blockId=2fe067c0-15d0-80fd-92d5-ed530c5d19e7)

#### 2. OverlayFS 마운트

이제 두 레이어를 하나의 통합 뷰로 마운트해봅시다.

```bash
# OverlayFS 마운트
sudo mount -t overlay overlay \
    -o lowerdir=lower,upperdir=upper,workdir=work \
    merged/

# 마운트 확인
mount | grep overlay
```

**각 디렉토리 역할:**

- `lowerdir`: 읽기 전용 레이어 (base layer)

- `upperdir`: 읽기/쓰기 레이어 (변경 사항이 저장됨)

- `workdir`: OverlayFS 내부 작업용 디렉토리 (반드시 빈 디렉토리여야 함)

- `merged`: 통합된 뷰가 보이는 마운트 포인트

![image](https://blog.pieroot.xyz/api/image-proxy?id=9b1e684f-9237-4bd3-b468-85c490a8ff3d&kind=s3&pageId=2ed067c0-15d0-8057-9d87-fe09ee46435a&source=block&blockId=2fe067c0-15d0-808d-b275-fe3a1e925600)

#### 3. 통합 뷰 확인

```bash
# merged 디렉토리 내용 확인
ls -la merged/

# 파일 내용 확인
cat merged/file1.txt   # lower에서 옴
cat merged/file2.txt   # upper에서 옴
cat merged/shared.txt  # upper의 내용이 표시됨 (upper 우선)
```

### 실습 시나리오

#### 시나리오 1: 파일 우선순위 확인

같은 이름의 파일이 lower와 upper 레이어에 모두 있을 때, upper 레이어의 파일이 우선 표시됩니다.

```bash
# shared.txt의 내용 확인 (upper가 우선)
cat merged/shared.txt

# 출력: Upper shared file
```

#### 시나리오 2: 쓰기 레이어에 파일 생성

```bash
# merged 디렉토리에 새 파일 생성
echo "New file in merged" > merged/newfile.txt

# upper에만 파일이 생성되었는지 확인
ls -la upper/
cat upper/newfile.txt
```

#### 시나리오 3: lower 레이어의 파일 수정 (Copy-on-Write)

```bash
# lower의 파일을 수정하려고 시도
echo "Modified content" > merged/file1.txt

# lower는 변경되지 않고, upper에 파일이 복사됨 (Copy-on-Write)
cat lower/file1.txt   # 원본 유지: "This is from lower layer"
cat upper/file1.txt   # 수정된 내용: "Modified content"
```

![image](https://blog.pieroot.xyz/api/image-proxy?id=9f471f69-6516-4a82-b103-ffe0b3cf1325&kind=s3&pageId=2ed067c0-15d0-8057-9d87-fe09ee46435a&source=block&blockId=2fe067c0-15d0-8091-8f39-caab756b2b1c)

#### 시나리오 4: 파일 삭제 시 whiteout 확인

```bash
# merged에서 lower의 파일 삭제
rm merged/file1.txt

# upper에 whiteout 파일이 생성됨
ls -la upper/

# character device로 whiteout 표시됨
# c--------- 0 0 0, 0 file1.txt
```

![image](https://blog.pieroot.xyz/api/image-proxy?id=b51c7a1c-b483-46ed-8892-f68262c8ca78&kind=s3&pageId=2ed067c0-15d0-8057-9d87-fe09ee46435a&source=block&blockId=2fe067c0-15d0-80c6-a584-f5319af34ebd)

### 고급 사용법

#### 여러 lower 레이어 마운트

OverlayFS는 여러 개의 lower 레이어를 지원합니다.

```bash
# 추가 레이어 생성
mkdir lower2
echo "Layer2 content" > lower2/file3.txt

# 마운트 해제
sudo umount merged/

# work 디렉토리 초기화 (중요!)
rm -rf work/*

# 여러 lower 레이어로 다시 마운트 (콜론으로 구분, 왼쪽이 상위)
sudo mount -t overlay overlay \
    -o lowerdir=lower2:lower,upperdir=upper,workdir=work \
    merged/

# 확인
ls -la merged/
```

#### 읽기 전용 마운트 (upperdir 없이)

```bash
# upper와 work 없이 읽기 전용으로 마운트
sudo mount -t overlay overlay \
    -o lowerdir=lower2:lower \
    merged/
```

#### 마운트 옵션 활용

```bash
# index 옵션 (하드링크 지원 향상)
sudo mount -t overlay overlay \
    -o lowerdir=lower,upperdir=upper,workdir=work,index=on \
    merged/

# metacopy 옵션 (메타데이터만 복사, 성능 향상)
sudo mount -t overlay overlay \
    -o lowerdir=lower,upperdir=upper,workdir=work,metacopy=on \
    merged/
```

### 실전 활용 예제

#### Docker와 유사한 레이어 구조 시뮬레이션

```bash
# Base 레이어 (OS 기본 파일)
mkdir -p demo/base
echo "Base OS files" > demo/base/system.conf

# Application 레이어
mkdir -p demo/app
echo "Application files" > demo/app/app.conf

# Configuration 레이어
mkdir -p demo/config
echo "User configuration" > demo/config/user.conf

# Runtime 레이어 (쓰기 가능)
mkdir -p demo/runtime demo/work demo/container

# 통합 마운트 (왼쪽이 상위 레이어)
sudo mount -t overlay overlay \
    -o lowerdir=demo/config:demo/app:demo/base,upperdir=demo/runtime,workdir=demo/work \
    demo/container/

# 컨테이너 뷰 확인
ls -la demo/container/
cat demo/container/system.conf
cat demo/container/app.conf
cat demo/container/user.conf
```

### 마운트 해제

```bash
# OverlayFS 마운트 해제
sudo umount merged/

# 정리
rm -rf ~/overlay-demo
```

### 트러블슈팅

#### 일반적인 문제와 해결방법

- **"wrong fs type" 또는 "overlay: missing 'workdir'" 오류**
  ```bash
  # workdir이 upperdir과 같은 파일시스템에 있어야 함
  # workdir은 반드시 비어있어야 함
  rm -rf work/*
  mkdir -p work
  ```

- **"workdir is in-use" 오류**
  ```bash
  # 기존 마운트 해제 후 work 디렉토리 초기화
  sudo umount merged/
  rm -rf work/*
  ```

- **Permission denied 오류**
  ```bash
  # root 권한 필요
  sudo mount -t overlay ...
  
  # 또는 /etc/fstab에 user 옵션 추가
  ```

- **overlay 모듈이 없을 때**
  ```bash
  # 모듈 로드
  sudo modprobe overlay
  
  # 부팅 시 자동 로드 설정
  echo "overlay" | sudo tee -a /etc/modules-load.d/overlay.conf
  ```

### 성능 테스트

#### 읽기 성능 측정

```bash
# 큰 파일 생성
dd if=/dev/zero of=lower/testfile bs=1M count=100

# 읽기 성능 테스트
time cat merged/testfile > /dev/null
```

#### 쓰기 성능 측정

```bash
# 쓰기 성능 테스트
time dd if=/dev/zero of=merged/writefile bs=1M count=100

# upper에 저장된 파일 확인
ls -lh upper/writefile
```

### unionfs-fuse vs OverlayFS 비교

### 정리

OverlayFS는 다음과 같은 특징을 가집니다:

- **커널 레벨 구현:** FUSE 기반보다 훨씬 빠른 성능

- **Copy-on-Write:** lower 레이어의 파일 수정 시 upper 레이어로 복사

- **다중 lower 레이어:** 여러 읽기 전용 레이어 지원

- **컨테이너 기술의 기반:** Docker, Podman 등에서 기본 스토리지 드라이버로 사용

#### 핵심 체크리스트 ✅

- [ ] 커널 버전 3.18 이상 확인

- [ ] overlay 모듈 로드 확인

- [ ] lower, upper, work, merged 디렉토리 구조 이해

- [ ] work 디렉토리는 항상 비어있어야 함

- [ ] upper와 work는 같은 파일시스템에 위치해야 함

### 참고 자료

- [Linux Kernel Documentation - Overlay Filesystem](https://www.kernel.org/doc/html/latest/filesystems/overlayfs.html)

- [Docker Storage Drivers - OverlayFS](https://docs.docker.com/storage/storagedriver/overlayfs-driver/)

- [ArchWiki - Overlay filesystem](https://wiki.archlinux.org/title/Overlay_filesystem)