FUSE (Filesystem in Userspace)

유저스페이스에서 파일시스템을 구현할 수 있게 해주는 FUSE 프레임워크의 아키텍처, 커널 모듈 내부, libfuse API, 프로토콜, virtiofs, 성능 최적화, 보안 모델을 종합적으로 다룹니다.

FUSE 개요

FUSE(Filesystem in Userspace)는 커널 모듈을 직접 작성하지 않고도 유저스페이스 프로그램으로 파일시스템을 구현할 수 있게 해주는 프레임워크입니다. 2005년 Linux 2.6.14에서 mainline에 통합되었으며, 현재까지 수백 개의 FUSE 기반 파일시스템이 활발히 사용되고 있습니다.

유저스페이스 파일시스템이 필요한 이유

• 개발 용이성 — 커널 프로그래밍 없이 C, Python, Go, Rust 등 일반 언어로 파일시스템 구현 가능
• 안정성 — 유저스페이스 프로세스 크래시가 커널 패닉을 유발하지 않음
• 빠른 프로토타이핑 — 커널 재컴파일 없이 파일시스템 로직을 즉시 수정/테스트
• 라이브러리 활용 — OpenSSL, libcurl, gRPC 등 유저스페이스 라이브러리를 자유롭게 사용
• non-root 마운트 — 일반 사용자도 fusermount를 통해 파일시스템 마운트 가능

FUSE 3계층 구조

FUSE는 세 가지 핵심 컴포넌트로 구성됩니다:

FUSE 아키텍처

요청/응답 흐름 상세

1. 애플리케이션이 open(), read() 등 시스템 콜 호출
2. VFS가 FUSE 파일시스템의 file_operations/inode_operations을 통해 FUSE 커널 모듈로 디스패치
3. FUSE 커널 모듈이 fuse_req 구조체를 생성하여 fuse_iqueue에 큐잉
4. 유저 데몬이 /dev/fuse에서 read()로 요청을 가져옴
5. 유저 데몬이 요청을 처리 (파일 읽기, 네트워크 I/O 등)
6. 유저 데몬이 /dev/fuse에 write()로 응답을 기록
7. FUSE 커널 모듈이 대기 중인 프로세스를 깨우고 결과 반환

FUSE 커널 모듈 내부

/dev/fuse 디바이스

/dev/fuse는 캐릭터 디바이스(major 10, minor 229)로, FUSE 커널 모듈과 유저스페이스 데몬 간의 통신 채널입니다. 데몬은 이 디바이스를 열어 read()로 요청을 수신하고 write()로 응답을 전송합니다.

/* fs/fuse/dev.c — /dev/fuse file operations */
const struct file_operations fuse_dev_operations = {
    .owner   = THIS_MODULE,
    .open    = fuse_dev_open,
    .read    = fuse_dev_read,      /* 유저 데몬이 요청을 읽음 */
    .write   = fuse_dev_write,     /* 유저 데몬이 응답을 기록 */
    .splice_read  = fuse_dev_splice_read,
    .splice_write = fuse_dev_splice_write,
    .poll    = fuse_dev_poll,
    .release = fuse_dev_release,
    .fasync  = fuse_dev_fasync,
};

fuse_conn (연결 관리)

struct fuse_conn은 하나의 FUSE 마운트와 연결된 유저 데몬 사이의 모든 상태를 관리하는 핵심 구조체입니다.

/* include/linux/fuse.h — 주요 필드 발췌 */
struct fuse_conn {
    unsigned max_read;               /* 최대 read 크기 */
    unsigned max_write;              /* 최대 write 크기 */
    unsigned max_pages;              /* 단일 요청 최대 페이지 수 */
    unsigned max_background;         /* 최대 배경 요청 수 */
    unsigned congestion_threshold;   /* 혼잡 시작 임계치 */
    unsigned num_background;         /* 현재 배경 요청 수 */
    struct fuse_iqueue iq;           /* 입력 큐 (pending 요청) */
    spinlock_t lock;                /* 연결 상태 보호 */
    unsigned minor;                  /* FUSE 프로토콜 마이너 버전 */
    unsigned conn_init:1;           /* FUSE_INIT 완료 여부 */
    unsigned writeback_cache:1;     /* writeback 캐시 활성화 */
    unsigned no_open:1;             /* OPEN 요청 생략 가능 */
    unsigned parallel_dirops:1;     /* 병렬 디렉토리 연산 */
};

fuse_iqueue / fuse_pqueue (요청/응답 큐)

FUSE는 두 가지 큐를 사용하여 요청을 관리합니다:

• fuse_iqueue (입력 큐) — 커널에서 유저스페이스로 전달 대기 중인 요청. 데몬의 read() 호출 시 이 큐에서 요청을 꺼냄
• fuse_pqueue (처리 큐) — 유저스페이스에서 처리 중인 요청. 데몬의 write() 응답과 매칭

요청 라이프사이클

/* struct fuse_req 주요 필드 */
struct fuse_req {
    struct list_head list;       /* 큐 연결 */
    u64 unique;                   /* 고유 요청 ID */
    struct fuse_in_header in;     /* 요청 헤더 */
    struct fuse_out_header out;   /* 응답 헤더 */
    wait_queue_head_t waitq;     /* 완료 대기 큐 */
    struct fuse_args *args;       /* 요청/응답 인자 */
    unsigned isreply:1;           /* 응답 필요 여부 */
    unsigned force:1;             /* 연결 중단 시에도 전송 */
    unsigned background:1;        /* 배경 요청 여부 */
};

/*
 * 요청 라이프사이클:
 * 1. fuse_simple_request() / fuse_simple_background()로 생성
 * 2. fuse_iqueue의 pending 리스트에 추가
 * 3. 데몬이 /dev/fuse read()로 요청 수신 → fuse_pqueue로 이동
 * 4. 데몬이 /dev/fuse write()로 응답 → fuse_req 완료
 * 5. 대기 중인 커널 스레드 깨움 → 결과 반환
 */

FUSE 프로토콜

fuse_in_header / fuse_out_header

모든 FUSE 메시지는 헤더로 시작합니다:

/* include/uapi/linux/fuse.h */
struct fuse_in_header {
    uint32_t len;       /* 메시지 전체 길이 (헤더 포함) */
    uint32_t opcode;    /* 작업 코드 (FUSE_LOOKUP, FUSE_READ 등) */
    uint64_t unique;    /* 고유 요청 ID (응답 매칭) */
    uint64_t nodeid;    /* 대상 inode 번호 */
    uint32_t uid;       /* 요청자 UID */
    uint32_t gid;       /* 요청자 GID */
    uint32_t pid;       /* 요청자 PID */
    uint32_t padding;
};

struct fuse_out_header {
    uint32_t len;       /* 응답 전체 길이 */
    int32_t  error;     /* 에러 코드 (0 = 성공, 음수 = errno) */
    uint64_t unique;    /* 요청의 unique와 매칭 */
};

주요 opcode 테이블

FUSE_INIT 핸드셰이크

마운트 시 커널과 유저 데몬 사이에 FUSE_INIT 메시지를 교환하여 프로토콜 버전과 기능 플래그를 협상합니다:

/* FUSE_INIT 요청/응답 */
struct fuse_init_in {
    uint32_t major;      /* 커널이 지원하는 메이저 버전 (7) */
    uint32_t minor;      /* 커널이 지원하는 마이너 버전 */
    uint32_t max_readahead;
    uint32_t flags;      /* 커널 지원 기능 플래그 */
    uint32_t flags2;     /* 확장 플래그 (7.36+) */
};

struct fuse_init_out {
    uint32_t major;      /* 데몬이 선택한 메이저 버전 */
    uint32_t minor;      /* 데몬이 선택한 마이너 버전 */
    uint32_t max_readahead;
    uint32_t flags;      /* 데몬이 활성화할 기능 */
    uint32_t max_background;
    uint32_t congestion_threshold;
    uint32_t max_write;
    uint32_t max_pages;  /* 7.28+ */
};

/* 주요 기능 플래그 */
#define FUSE_WRITEBACK_CACHE   (1 << 16)  /* writeback 캐시 */
#define FUSE_PARALLEL_DIROPS   (1 << 18)  /* 병렬 디렉토리 연산 */
#define FUSE_PASSTHROUGH       (1 << 26)  /* passthrough I/O (6.9+) */
#define FUSE_DO_READDIRPLUS    (1 << 13)  /* READDIRPLUS 지원 */
#define FUSE_SPLICE_READ       (1 << 7)   /* splice로 읽기 */
#define FUSE_SPLICE_WRITE      (1 << 8)   /* splice로 쓰기 */

FUSE_NOTIFY: 커널 → 유저 비동기 알림

커널은 유저 데몬에 비동기 알림을 보낼 수 있습니다. 이는 캐시 무효화 등에 사용됩니다:

• FUSE_NOTIFY_INVAL_INODE — inode 캐시 무효화
• FUSE_NOTIFY_INVAL_ENTRY — dentry 캐시 무효화
• FUSE_NOTIFY_STORE — 커널 캐시에 데이터 저장
• FUSE_NOTIFY_RETRIEVE — 커널 캐시에서 데이터 조회
• FUSE_NOTIFY_DELETE — 디렉토리 엔트리 삭제 알림

libfuse API

High-level API (경로 기반)

High-level API는 파일 경로를 기반으로 동작하며, 대부분의 FUSE 파일시스템이 이 API를 사용합니다:

/* fuse_operations: high-level API 콜백 테이블 */
struct fuse_operations {
    int  (*getattr)(const char *path, struct stat *st,
                     struct fuse_file_info *fi);
    int  (*readdir)(const char *path, void *buf,
                     fuse_fill_dir_t filler, off_t offset,
                     struct fuse_file_info *fi,
                     enum fuse_readdir_flags flags);
    int  (*open)(const char *path, struct fuse_file_info *fi);
    int  (*read)(const char *path, char *buf, size_t size,
                  off_t offset, struct fuse_file_info *fi);
    int  (*write)(const char *path, const char *buf,
                   size_t size, off_t offset,
                   struct fuse_file_info *fi);
    int  (*mkdir)(const char *path, mode_t mode);
    int  (*unlink)(const char *path);
    int  (*rmdir)(const char *path);
    int  (*rename)(const char *from, const char *to,
                    unsigned int flags);
    int  (*truncate)(const char *path, off_t size,
                      struct fuse_file_info *fi);
    int  (*create)(const char *path, mode_t mode,
                    struct fuse_file_info *fi);
    int  (*release)(const char *path, struct fuse_file_info *fi);
    int  (*fsync)(const char *path, int isdatasync,
                   struct fuse_file_info *fi);
    int  (*statfs)(const char *path, struct statvfs *st);
    void *(*init)(struct fuse_conn_info *conn,
                   struct fuse_config *cfg);
    void (*destroy)(void *private_data);
    /* ... */
};

Low-level API (inode 기반)

Low-level API는 inode 번호(nodeid)를 직접 다루며, 더 세밀한 제어가 가능합니다. 고성능 FUSE 파일시스템에서 사용합니다:

/* fuse_lowlevel_ops: low-level API 콜백 */
struct fuse_lowlevel_ops {
    void (*lookup)(fuse_req_t req, fuse_ino_t parent,
                    const char *name);
    void (*getattr)(fuse_req_t req, fuse_ino_t ino,
                     struct fuse_file_info *fi);
    void (*open)(fuse_req_t req, fuse_ino_t ino,
                  struct fuse_file_info *fi);
    void (*read)(fuse_req_t req, fuse_ino_t ino,
                  size_t size, off_t off,
                  struct fuse_file_info *fi);
    void (*write)(fuse_req_t req, fuse_ino_t ino,
                   const char *buf, size_t size,
                   off_t off, struct fuse_file_info *fi);
    void (*forget)(fuse_req_t req, fuse_ino_t ino,
                    uint64_t nlookup);
    /* ... */
};

/* Low-level API에서 응답은 명시적으로 전송해야 함 */
fuse_reply_entry(req, &entry_param);  /* LOOKUP 응답 */
fuse_reply_buf(req, buf, size);       /* READ 응답 */
fuse_reply_err(req, errno);           /* 에러 응답 */

fuse_session과 이벤트 루프

/* 싱글스레드 이벤트 루프 */
struct fuse_session *se = fuse_session_new(&args, &ops,
                                            sizeof(ops), userdata);
fuse_session_mount(se, mountpoint);
fuse_session_loop(se);               /* 싱글스레드 */

/* 멀티스레드 이벤트 루프 */
struct fuse_loop_config config = {
    .clone_fd = 1,        /* /dev/fuse fd를 복제하여 병렬 처리 */
    .max_idle_threads = 10,
};
fuse_session_loop_mt(se, &config);   /* 멀티스레드 */

FUSE 파일시스템 구현 예제

최소한의 FUSE 파일시스템 예제입니다. 읽기 전용으로 /hello 파일 하나를 제공합니다:

#define FUSE_USE_VERSION 31
#include <fuse3/fuse.h>
#include <string.h>
#include <errno.h>

static const char *hello_str = "Hello, FUSE!\n";
static const char *hello_path = "/hello";

static int hello_getattr(const char *path, struct stat *st,
                          struct fuse_file_info *fi)
{
    (void) fi;
    memset(st, 0, sizeof(struct stat));

    if (strcmp(path, "/") == 0) {
        st->st_mode = S_IFDIR | 0755;
        st->st_nlink = 2;
    } else if (strcmp(path, hello_path) == 0) {
        st->st_mode = S_IFREG | 0444;
        st->st_nlink = 1;
        st->st_size = strlen(hello_str);
    } else {
        return -ENOENT;
    }
    return 0;
}

static int hello_readdir(const char *path, void *buf,
                          fuse_fill_dir_t filler, off_t offset,
                          struct fuse_file_info *fi,
                          enum fuse_readdir_flags flags)
{
    (void) offset; (void) fi; (void) flags;
    if (strcmp(path, "/") != 0)
        return -ENOENT;

    filler(buf, ".",  NULL, 0, 0);
    filler(buf, "..", NULL, 0, 0);
    filler(buf, "hello", NULL, 0, 0);
    return 0;
}

static int hello_open(const char *path,
                       struct fuse_file_info *fi)
{
    if (strcmp(path, hello_path) != 0)
        return -ENOENT;
    if ((fi->flags & O_ACCMODE) != O_RDONLY)
        return -EACCES;
    return 0;
}

static int hello_read(const char *path, char *buf,
                       size_t size, off_t offset,
                       struct fuse_file_info *fi)
{
    size_t len;
    (void) fi;
    if (strcmp(path, hello_path) != 0)
        return -ENOENT;

    len = strlen(hello_str);
    if ((size_t)offset < len) {
        if (offset + size > len)
            size = len - offset;
        memcpy(buf, hello_str + offset, size);
    } else {
        size = 0;
    }
    return size;
}

static const struct fuse_operations hello_oper = {
    .getattr = hello_getattr,
    .readdir = hello_readdir,
    .open    = hello_open,
    .read    = hello_read,
};

int main(int argc, char *argv[])
{
    return fuse_main(argc, argv, &hello_oper, NULL);
}

빌드 및 실행

# 빌드 (libfuse3 필요)
gcc -Wall hello_fuse.c `pkg-config --cflags --libs fuse3` -o hello_fuse

# 마운트 포인트 생성 및 실행
mkdir -p /tmp/fuse_mnt
./hello_fuse /tmp/fuse_mnt

# 테스트
ls /tmp/fuse_mnt/           # hello
cat /tmp/fuse_mnt/hello     # Hello, FUSE!

# 언마운트
fusermount3 -u /tmp/fuse_mnt

마운트 메커니즘

fusermount3 / mount.fuse3

fusermount3는 non-root 사용자가 FUSE 파일시스템을 마운트/언마운트할 수 있게 해주는 setuid 헬퍼 프로그램입니다. 내부적으로 /dev/fuse를 열고, mount(2) 시스템 콜을 호출한 뒤, fd를 FUSE 데몬에 전달합니다.

/etc/fuse.conf

# /etc/fuse.conf — FUSE 전역 설정
user_allow_other    # allow_other 마운트 옵션 허용 (다른 사용자 접근)
mount_max = 1000    # 사용자당 최대 마운트 수

마운트 옵션 테이블

/proc/filesystems 확인

# FUSE 커널 모듈 로드 확인
grep fuse /proc/filesystems
# nodev   fuse
# nodev   fuseblk

# 현재 FUSE 마운트 확인
mount -t fuse,fuse.sshfs,fuseblk
# 또는
grep fuse /proc/mounts

성능 특성과 최적화

유저-커널 컨텍스트 스위칭 오버헤드

FUSE의 근본적인 성능 제약은 모든 파일시스템 요청이 커널 ↔ 유저스페이스 간 컨텍스트 스위칭을 수반한다는 점입니다. 단일 read() 호출이 최소 4번의 컨텍스트 스위칭을 발생시킵니다:

1. 애플리케이션 → 커널 (syscall)
2. 커널 → FUSE 데몬 (/dev/fuse read)
3. FUSE 데몬 → 커널 (/dev/fuse write)
4. 커널 → 애플리케이션 (syscall return)

FUSE writeback cache (kernel 3.15+)

writeback cache를 활성화하면 커널이 쓰기 데이터를 페이지 캐시에 버퍼링하여 배치 처리합니다. FUSE_INIT 시 FUSE_WRITEBACK_CACHE 플래그로 활성화합니다.

splice/zero-copy 전송

splice를 사용하면 유저스페이스 버퍼 복사 없이 커널 파이프를 통해 데이터를 전달할 수 있습니다. FUSE_SPLICE_READ/FUSE_SPLICE_WRITE 플래그로 활성화합니다.

max_background / congestion_threshold 튜닝

# 높은 병렬성이 필요한 워크로드에서 배경 요청 수 증가
./my_fuse_fs -o max_background=64,congestion_threshold=48 /mnt/fuse

# sysfs를 통한 런타임 확인
cat /sys/fs/fuse/connections/<N>/max_background
cat /sys/fs/fuse/connections/<N>/congestion_threshold

FUSE passthrough (kernel 6.9+)

FUSE passthrough는 데이터 I/O를 유저스페이스 데몬을 거치지 않고 커널에서 직접 백엔드 파일에 전달하는 기능입니다. 메타데이터 연산만 데몬이 처리하고, 실제 데이터 읽기/쓰기는 커널이 직접 수행하여 네이티브 파일시스템에 근접한 성능을 달성합니다.

/* passthrough 설정 (FUSE daemon 측) */
/* FUSE_INIT에서 FUSE_PASSTHROUGH 플래그 활성화 후 */
/* OPEN 응답 시 backing file의 fd를 전달 */

struct fuse_file_info fi;
fi.passthrough_fh = backing_fd;  /* 백엔드 파일 디스크립터 */
fi.direct_io = 0;
/* 이후 READ/WRITE는 커널이 backing_fd를 통해 직접 처리 */

벤치마크 비교

virtiofs (가상화 환경 FUSE)

아키텍처

virtiofs는 FUSE 프로토콜을 virtio 전송 계층 위에서 사용하여, 호스트와 게스트 VM 간에 고성능 파일시스템 공유를 제공합니다. 호스트 측에서 virtiofsd 데몬이 실행되고, 게스트에서 virtio-fs 커널 드라이버가 FUSE 요청을 virtio 큐를 통해 전달합니다.

DAX (Direct Access) 모드

DAX 모드에서는 호스트의 페이지 캐시를 게스트 VM에 직접 매핑하여 데이터 복사를 제거합니다. 메모리 매핑된 파일 접근이 네이티브에 가까운 성능을 달성합니다.

QEMU/libvirt 설정 예제

# 1. virtiofsd 데몬 실행 (Rust 구현, 권장)
/usr/libexec/virtiofsd \
    --socket-path=/tmp/virtiofs.sock \
    --shared-dir=/path/to/shared \
    --cache=always

# 2. QEMU에서 virtiofs 디바이스 추가
qemu-system-x86_64 \
    -chardev socket,id=char0,path=/tmp/virtiofs.sock \
    -device vhost-user-fs-pci,chardev=char0,tag=myfs \
    -object memory-backend-memfd,id=mem,size=4G,share=on \
    -numa node,memdev=mem \
    ...

# 3. 게스트 내부에서 마운트
mount -t virtiofs myfs /mnt/shared

컨테이너 환경 활용

Kata Containers는 virtiofs를 사용하여 컨테이너 이미지와 볼륨을 경량 VM 내부에 공유합니다. 이를 통해 컨테이너 수준의 편의성과 VM 수준의 격리를 동시에 달성합니다.

보안 모델

non-root 마운트와 보안 고려사항

FUSE는 일반 사용자가 파일시스템을 마운트할 수 있는 유일한 커널 메커니즘입니다. 이로 인해 다음과 같은 보안 고려사항이 존재합니다:

• 기본 접근 제한 — FUSE 마운트는 기본적으로 마운트한 사용자만 접근 가능 (다른 사용자/root도 접근 불가)
• 데몬 신뢰성 — FUSE 데몬이 악의적인 응답을 반환할 수 있음 (예: getattr에서 거짓 권한 반환)
• DoS 가능성 — 데몬이 응답하지 않으면 해당 마운트에 접근하는 프로세스가 영구 대기(hang)

default_permissions vs 커스텀 접근 제어

allow_other / allow_root

• allow_other — 모든 사용자가 마운트 포인트에 접근 가능. /etc/fuse.conf에 user_allow_other가 설정되어야 사용 가능
• allow_root — root만 추가 접근 허용. allow_other와 동시 사용 불가

namespace 격리 (user namespace + FUSE)

Linux 4.18+에서는 user namespace 내에서 FUSE 마운트가 가능합니다. 이를 통해 비특권 컨테이너에서도 FUSE 파일시스템을 사용할 수 있습니다:

# unprivileged user namespace에서 FUSE 마운트
unshare --user --mount --map-root-user -- bash -c \
    "./my_fuse_fs /mnt/fuse"

신뢰할 수 없는 FUSE 데몬 방어

실제 FUSE 파일시스템

CephFS와 Ceph 커널 통합

Ceph는 RADOS(Reliable Autonomic Distributed Object Store) 기반의 통합 분산 스토리지 시스템으로, 오브젝트 스토리지(RADOS Gateway), 블록 스토리지(RBD), 파일시스템(CephFS)을 단일 클러스터에서 제공합니다. 리눅스 커널에는 CephFS 커널 클라이언트(fs/ceph/), RBD 블록 드라이버(drivers/block/rbd.c), 공통 RADOS 클라이언트 라이브러리(net/ceph/)가 포함되어 있습니다.

Ceph 스토리지 아키텍처

핵심 컴포넌트

• RADOS — 모든 Ceph 서비스의 기반이 되는 오브젝트 스토어. 데이터를 오브젝트 단위로 OSD에 분산 저장하며, 복제(replication) 또는 이레이저 코딩(erasure coding)으로 내결함성 보장
• OSD (Object Storage Daemon) — 실제 디스크를 관리하는 데몬. 디스크당 하나의 OSD가 실행되며, BlueStore(기본) 또는 FileStore 백엔드를 사용
• MON (Monitor) — 클러스터 맵(OSDMap, CRUSHMap, MonMap, MgrMap, MDSMap)을 관리. Paxos 합의 알고리즘으로 3~5개 MON이 quorum 유지
• MDS (Metadata Server) — CephFS 전용 메타데이터 서버. 디렉토리 구조, inode 정보, 파일 잠금을 관리. 동적 서브트리 파티셔닝으로 수평 확장
• CRUSH 알고리즘 — 클라이언트가 중앙 조회 없이 오브젝트의 저장 위치를 직접 계산. CRUSH 맵에 정의된 토폴로지(rack, host, OSD)와 배치 규칙에 따라 데이터 분배

CRUSH 매핑 과정

/* CRUSH 데이터 배치 계산 흐름 */
파일 → 스트라이핑 → 오브젝트명 결정
  │
  ├─ object name = {inode}.{stripe_unit_number}
  │
  ▼
오브젝트 → PG(Placement Group) 매핑
  │
  ├─ pgid = hash(object_name) % pg_num
  │
  ▼
PG → OSD set 매핑 (CRUSH 알고리즘)
  │
  ├─ CRUSH(pgid, crush_map, rule) → [osd.3, osd.7, osd.12]
  │                                   primary  replicas
  ▼
클라이언트가 primary OSD에 직접 I/O 요청

CephFS 커널 클라이언트 (fs/ceph/)

CephFS 커널 클라이언트는 fs/ceph/ 디렉토리에 구현되어 있으며, VFS 계층에 직접 통합됩니다. FUSE 클라이언트와 달리 유저-커널 컨텍스트 스위칭 없이 커널 내에서 모든 I/O를 처리하므로 더 높은 성능을 제공합니다.

/* fs/ceph/super.h — CephFS 핵심 구조체 */
struct ceph_fs_client {
    struct super_block *sb;              /* VFS 슈퍼블록 */
    struct ceph_client *client;          /* libceph 클라이언트 (net/ceph/) */
    struct ceph_mds_client *mdsc;        /* MDS 클라이언트 */
    unsigned long mount_options;          /* 마운트 옵션 플래그 */
    unsigned max_file_size;               /* MDS가 허용한 최대 파일 크기 */

    struct ceph_mount_options *mount_opt;  /* 파싱된 마운트 옵션 */
    struct workqueue_struct *inode_wq;     /* inode 작업 큐 */
    struct workqueue_struct *cap_wq;       /* capability 처리 큐 */
    atomic_long_t writeback_count;        /* writeback 진행 수 */
};

/* fs/ceph/inode.c — CephFS inode 확장 정보 */
struct ceph_inode_info {
    struct inode netfs_inode.inode;       /* VFS inode (내장) */
    struct ceph_vino i_vino;             /* Ceph vino (ino + snap) */
    u64 i_version;                        /* inode 버전 */
    u64 i_max_size;                       /* MDS 허가 최대 크기 */

    struct rb_root i_caps;               /* 보유 cap 트리 */
    int i_nr_by_mode[CEPH_FILE_MODE_BITS]; /* 모드별 열린 파일 수 */
    u32 i_time_warp_seq;                  /* 타임스탬프 일관성 */

    struct ceph_file_layout i_layout;    /* 파일 레이아웃 (스트라이핑) */
    struct ceph_snap_realm *i_snap_realm; /* 스냅샷 영역 */
    struct list_head i_snap_realm_item;  /* 스냅샷 영역 연결 */
    struct list_head i_snap_flush_item;  /* 스냅샷 플러시 연결 */
};

MDS 통신과 Capability (Caps) 시스템

CephFS의 가장 독특한 특징은 capability(cap) 기반의 캐시 일관성 프로토콜입니다. MDS는 클라이언트에게 파일/디렉토리에 대한 cap을 발급하고, 클라이언트는 cap이 허용하는 범위 내에서 MDS에 요청하지 않고 로컬 캐시를 사용할 수 있습니다.

/* fs/ceph/caps.c — cap 메시지 처리 핵심 흐름 */

/*
 * MDS → 클라이언트: cap 발급/회수 흐름
 *
 * 1. 클라이언트가 open() → MDS에 CEPH_MDS_OP_OPEN 요청
 * 2. MDS가 cap 발급 (예: pAsLsXsFscrwb)
 * 3. 클라이언트가 cap 범위 내에서 로컬 캐시 사용
 * 4. 다른 클라이언트가 같은 파일 접근 시 MDS가 cap 회수(revoke)
 * 5. 클라이언트가 더티 데이터 플러시 후 cap 반환
 */

static void handle_cap_grant(struct inode *inode,
                              struct ceph_mds_caps *grant,
                              struct ceph_mds_session *session)
{
    struct ceph_inode_info *ci = ceph_inode(inode);
    int issued = __ceph_caps_issued(ci, NULL);
    int wanted = __ceph_caps_wanted(ci);
    int newcaps = le32_to_cpu(grant->caps);

    /* 새로 발급된 cap 확인 */
    int new_issued = ~issued & newcaps;

    /* 회수된 cap의 더티 데이터 플러시 */
    if ((issued & ~newcaps) & CEPH_CAP_FILE_BUFFER)
        ceph_queue_writeback(inode);  /* 버퍼링된 쓰기 즉시 플러시 */

    /* 페이지 캐시 무효화 (읽기 cap 회수 시) */
    if ((issued & ~newcaps) & CEPH_CAP_FILE_SHARED)
        invalidate_mapping_pages(&inode->i_data, 0, -1);

    ci->i_issued = newcaps;
    /* ... */
}

CephFS 파일 레이아웃과 스트라이핑

/* include/linux/ceph/ceph_fs.h — 파일 레이아웃 구조체 */
struct ceph_file_layout {
    u32 stripe_unit;    /* 스트라이프 단위 크기 (기본 4MB) */
    u32 stripe_count;   /* 동시 스트라이프 수 (기본 1) */
    u32 object_size;    /* RADOS 오브젝트 크기 (기본 4MB) */
    s64 pool_id;        /* 데이터 풀 ID */
};

/*
 * 파일 → RADOS 오브젝트 매핑:
 *
 * stripe_unit=4M, stripe_count=4, object_size=4M 일 때:
 *
 * File offset:  [0-4M) [4M-8M) [8M-12M) [12M-16M) [16M-20M) ...
 * Object:        obj.0   obj.1   obj.2    obj.3     obj.0  ...
 * Stripe unit:     0       1       2        3         4    ...
 *
 * object_name = "{ino}.{objno:08x}"
 * objno = stripe_unit_num / stripe_count + (stripe_unit_num % stripe_count)
 */

CephFS 커널 마운트

# 커널 클라이언트로 CephFS 마운트 (v2 messenger 프로토콜)
mount -t ceph mon1:6789,mon2:6789,mon3:6789:/ /mnt/cephfs \
    -o name=admin,secret=AQBxxxxxxxxxxxxxxxxxxxxx==

# ceph.conf의 keyring 사용 (권장)
mount -t ceph mon1,mon2,mon3:/ /mnt/cephfs -o name=fs_client

# 주요 마운트 옵션
mount -t ceph mon1:/ /mnt/cephfs -o \
    name=admin,\
    readdir_max_entries=4096,\     # readdir 배치 크기 (기본 1024)
    rsize=16777216,\               # 최대 읽기 크기 (16MB)
    wsize=16777216,\               # 최대 쓰기 크기 (16MB)
    rasize=8388608,\               # readahead 크기 (8MB)
    caps_wanted_delay_max=60,\     # cap 요청 최대 지연 (초) 
    mds_namespace=myfs,\           # 특정 CephFS 인스턴스 지정
    recover_session=clean          # 세션 복구 모드

# 서브디렉토리만 마운트 (MDS 권한 제한 활용)
mount -t ceph mon1:/data/project /mnt/project -o name=project_user

# /etc/fstab 영속 마운트
# mon1,mon2,mon3:/  /mnt/cephfs  ceph  name=admin,noatime,_netdev  0 0

ceph-fuse (FUSE 클라이언트)

ceph-fuse는 CephFS의 유저스페이스 FUSE 클라이언트입니다. 커널 클라이언트와 같은 libcephfs 라이브러리를 사용하지만, FUSE를 통해 커널과 통신합니다. 새로운 기능이 커널에 반영되기 전에 먼저 사용할 수 있고, 커널 버전에 의존하지 않는 장점이 있습니다.

# ceph-fuse로 CephFS 마운트
ceph-fuse /mnt/cephfs --id admin

# 서브디렉토리 마운트
ceph-fuse /mnt/project --id project_user --client-mountpoint=/data/project

# 성능 튜닝 옵션
ceph-fuse /mnt/cephfs --id admin \
    --client-cache-size=16384 \          # 캐시 inode 수
    --fuse-big-writes \                  # 대용량 write 활성화
    --fuse-max-write=131072 \            # 최대 write 크기
    --client-readahead-max-bytes=8388608 # readahead 최대 크기

커널 클라이언트 vs FUSE 클라이언트 비교

RBD (RADOS Block Device) 커널 모듈

RBD는 RADOS 오브젝트 위에 블록 디바이스 인터페이스를 제공하는 커널 모듈입니다. drivers/block/rbd.c에 구현되어 있으며, VM 디스크 이미지(QEMU/KVM), 컨테이너 PV(Kubernetes CSI) 등에 널리 사용됩니다.

/* drivers/block/rbd.c — RBD 핵심 구조체 */
struct rbd_device {
    struct rbd_client *rbd_client;  /* RADOS 클라이언트 연결 */
    struct rbd_spec *spec;          /* pool/image/snap 명세 */
    struct rbd_layout layout;       /* 오브젝트 레이아웃 */
    u64 header_oid;                  /* 이미지 헤더 오브젝트 */

    struct gendisk *disk;           /* 블록 디바이스 */
    struct request_queue *rq;       /* I/O 요청 큐 */

    u64 mapping_size;                /* 이미지 크기 */
    u32 stripe_unit;                 /* 스트라이프 단위 (기본 4MB) */
    u32 stripe_count;                /* 스트라이프 수 */
    u32 obj_order;                   /* 오브젝트 크기 = 2^obj_order */

    unsigned long flags;             /* read-only, exclusive lock 등 */
    struct rbd_obj_request *obj_req; /* 진행 중인 오브젝트 요청 */
};

/*
 * RBD I/O 흐름:
 * 1. 블록 I/O 요청 (struct bio) 수신
 * 2. 오브젝트 경계로 분할: offset → object_name + object_offset
 * 3. 각 오브젝트에 대해 RADOS OSD 요청 생성
 * 4. OSD가 응답하면 블록 요청 완료
 *
 * object_name = "rbd_data.{image_id}.{objnum:016x}"
 * objnum = offset >> obj_order
 */

RBD 이미지 관리 및 매핑

# RBD 이미지 생성 (100GB, format 2)
rbd create mypool/myimage --size 102400 --image-format 2

# 이미지 정보 확인
rbd info mypool/myimage
# rbd image 'myimage':
#     size 100 GiB in 25600 objects
#     order 22 (4 MiB objects)
#     stripe unit: 4 MiB  stripe count: 1
#     features: layering, exclusive-lock, object-map, fast-diff, deep-flatten

# 커널에 블록 디바이스로 매핑
rbd map mypool/myimage --id admin
# /dev/rbd0

# 파일시스템 생성 및 마운트
mkfs.ext4 /dev/rbd0
mount /dev/rbd0 /mnt/rbd

# 매핑 해제
umount /mnt/rbd
rbd unmap /dev/rbd0

# 현재 매핑된 RBD 디바이스 확인
rbd showmapped
# id  pool     image    snap  device
# 0   mypool   myimage  -     /dev/rbd0

RBD 고급 기능

# RBD 스냅샷 및 클론 워크플로우
# 1. 스냅샷 생성
rbd snap create mypool/base-image@snap1

# 2. 스냅샷 보호 (클론 전 필수)
rbd snap protect mypool/base-image@snap1

# 3. COW 클론 생성 (즉시 완료, 데이터 복사 없음)
rbd clone mypool/base-image@snap1 mypool/vm-instance-01

# 4. 클론 독립화 (선택적: 부모 의존 제거)
rbd flatten mypool/vm-instance-01

libceph — 커널 RADOS 클라이언트 (net/ceph/)

net/ceph/에 구현된 libceph는 CephFS 커널 클라이언트와 RBD가 공통으로 사용하는 커널 내 RADOS 클라이언트 라이브러리입니다. MON/OSD 통신, CRUSH 계산, 메시지 프로토콜, 인증을 담당합니다.

/* net/ceph/ceph_common.c — libceph 핵심 구조체 */
struct ceph_client {
    struct ceph_options *options;       /* MON 주소, 인증 정보 등 */
    struct ceph_messenger msgr;         /* 메시지 전송 계층 */
    struct ceph_mon_client monc;        /* MON 클라이언트 */
    struct ceph_osd_client osdc;        /* OSD 클라이언트 */
};

/* net/ceph/osd_client.c — OSD 클라이언트 */
struct ceph_osd_client {
    struct ceph_client *client;
    struct ceph_osdmap *osdmap;        /* OSD 맵 (CRUSH 맵 포함) */
    struct rb_root osds;               /* 활성 OSD 연결 트리 */
    struct rb_root linger_requests;    /* watch/notify 요청 */
    struct list_head osd_lru;          /* OSD 연결 LRU */
    atomic64_t last_tid;               /* 마지막 요청 ID */
};

/* OSD 요청 흐름 */
struct ceph_osd_request *req;
req = ceph_osdc_new_request(&client->osdc, layout,
                             vino, offset, &len,
                             0,              /* num_ops */
                             CEPH_OSD_OP_READ,
                             CEPH_OSD_FLAG_READ,
                             NULL, 0);
ceph_osdc_start_request(&client->osdc, req);
ceph_osdc_wait_request(&client->osdc, req); /* 동기 대기 */

Messenger v2 프로토콜

Ceph Nautilus(14.x)부터 기본 사용되는 messenger v2 프로토콜은 net/ceph/messenger_v2.c에 구현되어 있습니다. v1 대비 프로토콜 협상 개선, CRC/암호화 선택, frame 기반 메시지 구조를 제공합니다.

Ceph 커널 모듈 디버깅

# debugfs를 통한 CephFS/RBD 상태 확인
mount -t debugfs none /sys/kernel/debug    # debugfs 마운트 (미마운트 시)

# CephFS 클라이언트 정보
ls /sys/kernel/debug/ceph/
# 8b3d5f2a-xxxx-xxxx-xxxx-xxxxxxxxxxxx.client12345/

# MDS 세션 및 cap 상태
cat /sys/kernel/debug/ceph/*/mdsc         # MDS 클라이언트 상태
cat /sys/kernel/debug/ceph/*/caps         # 보유 cap 수 통계
cat /sys/kernel/debug/ceph/*/mds_sessions # MDS 세션 상태

# OSD 클라이언트 상태
cat /sys/kernel/debug/ceph/*/osdc         # OSD 요청 상태
cat /sys/kernel/debug/ceph/*/osdmap       # OSD 맵 epoch
cat /sys/kernel/debug/ceph/*/monc         # MON 클라이언트 상태

# 동적 디버그 메시지 활성화
echo 'module ceph +p' > /sys/kernel/debug/dynamic_debug/control
echo 'module rbd +p' > /sys/kernel/debug/dynamic_debug/control
echo 'module libceph +p' > /sys/kernel/debug/dynamic_debug/control

# 특정 파일/함수만 디버그
echo 'file fs/ceph/caps.c +p' > /sys/kernel/debug/dynamic_debug/control
echo 'func ceph_check_caps +p' > /sys/kernel/debug/dynamic_debug/control

# dmesg에서 Ceph 관련 메시지 확인
dmesg | grep -i ceph

일반적인 문제와 해결

디버깅과 트러블슈팅

기본 디버깅 옵션

# -d: 디버그 모드 (모든 FUSE 메시지를 stderr에 출력, 포그라운드 실행 포함)
./my_fuse_fs -d /mnt/fuse

# -f: 포그라운드 실행 (데몬화하지 않음)
./my_fuse_fs -f /mnt/fuse

# -s: 싱글스레드 모드 (디버깅 시 유용)
./my_fuse_fs -f -s /mnt/fuse

강제 언마운트

# 정상 언마운트
fusermount3 -u /mnt/fuse

# 데몬이 응답하지 않을 때 강제 언마운트
fusermount3 -uz /mnt/fuse    # lazy unmount (-z)

# root 권한으로 강제 언마운트
umount -l /mnt/fuse          # lazy unmount
umount -f /mnt/fuse          # force unmount

strace로 /dev/fuse 트래픽 추적

# FUSE 데몬의 /dev/fuse 통신 추적
strace -f -e read,write -p <FUSE_DAEMON_PID>

# 특정 파일 디스크립터만 추적 (fd 번호 확인 후)
ls -la /proc/<PID>/fd/ | grep /dev/fuse
strace -f -e trace=read,write -e read=<fd> -e write=<fd> -p <PID>

/sys/fs/fuse/connections/ 디버그 인터페이스

# FUSE 연결 목록 확인
ls /sys/fs/fuse/connections/
# 42/  43/  ...

# 연결 상태 확인
cat /sys/fs/fuse/connections/42/waiting      # 대기 중인 요청 수
cat /sys/fs/fuse/connections/42/max_background
cat /sys/fs/fuse/connections/42/congestion_threshold

# 연결 강제 중단 (데몬 hang 시)
echo 1 > /sys/fs/fuse/connections/42/abort