Barebox · source analysis

envfs load와 default environment

영속 envfs image를 검증해 디렉터리로 펼치고 default environment와 합치는 과정을 읽습니다.

Series
11 / 19
Baseline
v2026.06.1
Commit
314c679eea2d
Source
common/environment.c:422-510 (발췌 범위)

envfs load와 default environment 단계에서 실제로 바뀌는 상태는 무엇인가?

U-Boot의 key-value blob과 달리 Barebox 환경은 파일과 script 중심이다. 저장 image의 CRC와 entry별 직접 파일 쓰기, 부팅 시 default overlay 순서를 확인한다.

부팅에서는 built-in default environment를 먼저 읽고 외부 envfs를 /env에 추가한다. 전체 CRC 검증은 파일 쓰기보다 앞서지만, entry 처리나 쓰기 중 오류가 나면 앞서 덮은 파일이 남을 수 있다.

객체와 주소가 놓이는 구조

그림 1. envfs load와 default environment에서 입력, 내부 상태, 출력의 경계
입력과 전제내부 상태외부로 공개되는 결과
01envfs image
02superblock/inodes
03runtime directory
04global variables

envfs_super / environment directory를 중심에 놓고 왼쪽의 입력이 어떤 검사를 거쳐 오른쪽 결과로 공개되는지 표시했다. 실제 디버깅에서는 각 블록의 주소와 크기를 로그에 대입한다.

envfs_load()의 파일 적용 경로

그림 2. CRC 검증 뒤 대상 directory에 바로 쓰기
envfs file/cdev
superblock CRC
data CRC
envfs_load_data
/env 파일·script

envfs_load()는 superblock과 전체 data CRC를 검사한 뒤 envfs_load_data()를 호출한다. 이 경로에는 압축 해제나 임시 directory 교체가 없다. force-builtin flag는 별도로 defaultenv_load()를 호출한다.

단계별 입력과 출력

고정 v2026.06.1의 부팅 기본 환경, envfs 이미지 검증, 대상 파일 쓰기를 구분한다. 전체 CRC 성공은 개별 파일 쓰기의 원자성을 뜻하지 않는다.

#단계진입 시 신뢰할 상태성공 뒤 남아야 할 상태다음 소비자
01startup.cCONFIG_DEFAULT_ENVIRONMENTbuilt-in default 파일을 /env에 load외부 envfs autoload는 설정에 따라 후속
02envfs_load()외부 envfs file/cdevsuperblock magic·CRC·size 확인force-builtin flag면 defaultenv_load 분기
03envfs_check_data()읽어 온 image data전체 data CRC 검증실패하면 파일 적용 전에 반환
04envfs_load_data()각 inode name·mode·content대상 경로에 symlink 또는 O_TRUNC 파일 쓰기기존 파일을 entry별로 즉시 변경
05envfs_load() 반환entry 처리 결과0 반환만으로 모든 entry 성공을 보증하지 않음후반 entry 오류 시 앞선 변경의 rollback 없음

분석 범위의 전제와 비교해, 다음 단계에 잘못된 입력을 넘긴 부분부터 조사한다.

CRC 검증과 파일 변경 시점을 그림으로 읽기

아래 그림은 메모리 주소가 아니라 외부 envfs image를 /env에 적용하는 순서다. CRC 검증 전과 첫 파일 변경 뒤의 오류 결과가 다르다.

그림 3. envfs 전체 CRC 이후 entry별 직접 쓰기

고정 environment.c와 envfs-core.c의 load 경로다. defaultenv_load()는 부팅 초기화 또는 force-builtin flag의 별도 분기다.

01file + superblock
02magic·CRC 확인
03image data CRC
04inode 순회
05대상 파일 직접 쓰기
그림 4. default environment와 persistent envfs

두 열의 객체는 이름이 비슷해도 생성 시점, 사용 가능한 API와 해제 책임이 다르다.

Default

01binary에 포함

02복구 기준

03build-time 원본

04build version 의존

05부팅 시 먼저 load

Persistent

01storage image

02사용자 수정

03saveenv 결과

04전원 차단 위험

05default 위에 적용

원본 코드

아래 코드는 Barebox v2026.06.1의 common/environment.c에서 422-510줄을 그대로 가져온 것이다.

commit314c679eea2d0ca847c64d1b646a1cf91225c0ecanchor · L446int envfs_load(const char *filename
422	defenv_path = default_environment_path_get();
423	if (defenv_path && !strcmp(filename, defenv_path))
424	    nv_var_set_clean();
425#endif
426out:
427	close(envfd);
428out1:
429	free(buf);
430#ifdef __BAREBOX__
431	unlink_recursive(TMPDIR, NULL);
432#endif
433	return ret;
434}
435EXPORT_SYMBOL(envfs_save);
436
437/**
438 * Restore the last environment into the current one
439 * @param[in] filename from where to restore
440 * @param[in] dir where to store the last content
441 * @return 0 on success, anything else in case of failure
442 *
443 * Note: This function will also be used on the host! See note in the header
444 * of this file.
445 */
446int envfs_load(const char *filename, const char *dir, unsigned flags)
447{
448	struct envfs_super super;
449	void *buf = NULL, *rbuf;
450	int envfd;
451	int ret = 0;
452	size_t size, rsize;
453	__maybe_unused const char *defenv_path;
454
455#ifdef __BAREBOX__
456	if (!IS_ALLOWED(SCONFIG_ENVIRONMENT_LOAD))
457		return -EPERM;
458#endif
459
460	if (!filename)
461		filename = default_environment_path_get();
462	if (!filename)
463		return -ENOENT;
464
465	if (!dir)
466		dir = "/env";
467
468	envfd = open(filename, O_RDONLY);
469	if (envfd < 0) {
470		printf("environment load %s: %m\n", filename);
471		if (errno == ENOENT)
472			printf("Maybe you have to create the partition.\n");
473		return -1;
474	}
475
476	/* read superblock */
477	ret = read(envfd, &super, sizeof(struct envfs_super));
478	if ( ret < sizeof(struct envfs_super)) {
479		perror("read");
480		ret = -errno;
481		goto out;
482	}
483
484	ret = envfs_check_super(&super, &size);
485	if (ret)
486		goto out;
487
488	if (super.flags & ENVFS_FLAGS_FORCE_BUILT_IN) {
489		printf("found force-builtin environment, using defaultenv\n");
490		ret = defaultenv_load(dir, 0);
491		if (ret)
492			printf("failed to load default environment: %s\n",
493					strerror(-ret));
494		goto out;
495	}
496
497	buf = xmalloc(size);
498
499	rbuf = buf;
500	rsize = size;
501
502	while (rsize) {
503		ssize_t now;
504
505		now = read(envfd, rbuf, rsize);
506		if (now < 0) {
507			perror("read");
508			ret = -errno;
509			goto out;
510		}

발췌 범위와 읽기 기준

원문 422-510줄에는 앞뒤 문맥이 포함됩니다. 기준 구문 int envfs_load(const char *filename은 L446에 있습니다. 발췌 첫 줄을 함수 정의의 시작으로 해석하지 않습니다.

U-Boot의 key-value blob과 달리 Barebox 환경은 파일과 script 중심이다. 저장 image의 CRC와 entry별 직접 파일 쓰기, 부팅 시 default overlay 순서를 확인한다.

이 파일의 helper는 host에서도 사용된다. 환경 적용을 항상 부트 CPU 실행으로 제한하지 않는다. CRC는 손상 검출이며 입력의 신뢰성이나 모든 경로·크기 검사를 대신하지 않는다.

함께 읽어야 하는 원본 코드

첫 코드 조각만으로 동작이 완성되지 않는 경우 호출 매크로, 객체 정의와 실제 실행 목록을 같은 페이지에 묶었다. 각 조각은 같은 기준 commit에서 가져왔다.

01. runtime environment를 envfs image로 직렬화

common/environment.c 295-397줄이다.

filecommon/environment.canchor · L305int envfs_save
295/**
296 * Make the current environment persistent
297 * @param[in] filename where to store
298 * @param[in] dirname what to store (all files in this dir)
299 * @param[in] flags superblock flags (refer ENVFS_FLAGS_* macros)
300 * @return 0 on success, anything else in case of failure
301 *
302 * Note: This function will also be used on the host! See note in the header
303 * of this file.
304 */
305int envfs_save(const char *filename, const char *dirname, unsigned flags)
306{
307	struct envfs_super *super;
308	int envfd, size, ret;
309	struct action_data data = {};
310	void *buf = NULL, *wbuf;
311	struct envfs_entry *env;
312	__maybe_unused const char *defenv_path;
313
314	if (!filename)
315		return -ENOENT;
316
317	if (!dirname)
318		dirname = "/env";
319
320	data.writep = NULL;
321	data.base = dirname;
322
323#ifdef __BAREBOX__
324	defaultenv_load(TMPDIR, 0);
325#endif
326
327	if (flags & ENVFS_FLAGS_FORCE_BUILT_IN) {
328		size = 0; /* force no content */
329	} else {
330		/* first pass: calculate size */
331		recursive_action(dirname, ACTION_RECURSE | ACTION_SORT, file_action,
332				NULL, &data, 0);
333		recursive_action("/.defaultenv", ACTION_RECURSE | ACTION_SORT,
334				file_remove_action, NULL, &data, 0);
335		size = 0;
336
337		for (env = data.env; env; env = env->next) {
338			size += PAD4(env->size);
339			size += sizeof(struct envfs_inode);
340			size += PAD4(strlen(env->name) + 1);
341			size += sizeof(struct envfs_inode_end);
342		}
343	}
344
345	buf = xzalloc(size + sizeof(struct envfs_super));
346	data.writep = buf + sizeof(struct envfs_super);
347
348	super = buf;
349	super->magic = ENVFS_32(ENVFS_MAGIC);
350	super->major = ENVFS_MAJOR;
351	super->minor = ENVFS_MINOR;
352	super->size = ENVFS_32(size);
353	super->flags = ENVFS_32(flags);
354
355	if (!(flags & ENVFS_FLAGS_FORCE_BUILT_IN)) {
356		/* second pass: copy files to buffer */
357		env = data.env;
358		while (env) {
359			struct envfs_entry *next = env->next;
360
361			envfs_save_inode(&data, env);
362
363			free(env->buf);
364			free(env->name);
365			free(env);
366			env = next;
367		}
368	}
369
370	super->crc = ENVFS_32(crc32(0, buf + sizeof(struct envfs_super), size));
371	super->sb_crc = ENVFS_32(crc32(0, buf, sizeof(struct envfs_super) - 4));
372
373	envfd = open(filename, O_WRONLY | O_CREAT, S_IRUSR | S_IWUSR);
374	if (envfd < 0) {
375		printf("could not open %s: %m\n", filename);
376		ret = -errno;
377		goto out1;
378	}
379
380	ret = protect(envfd, ~0, 0, 0);
381
382	/* ENOSYS and EOPNOTSUPP aren't errors here, many devices don't need it */
383	if (ret && errno != ENOSYS && errno != EOPNOTSUPP) {
384		printf("could not unprotect %s: %m\n", filename);
385		goto out;
386	}
387
388	ret = erase(envfd, ERASE_SIZE_ALL, 0, ERASE_TO_WRITE);
389
390	/* ENOSYS and EOPNOTSUPP aren't errors here, many devices don't need it */
391	if (ret && errno != ENOSYS && errno != EOPNOTSUPP) {
392		printf("could not erase %s: %m\n", filename);
393		goto out;
394	}
395
396	size += sizeof(struct envfs_super);
397

CRC 검사와 파일 적용의 경계

파일을 바꾸기 전의 검사

envfs_load()는 허용 설정과 입력 경로를 확인하고 superblock magic·CRC를 검사한다. force-builtin이면 외부 data 처리를 건너뛰고 defaultenv_load()로 분기한다. 일반 경로는 data 전체를 읽어 CRC가 맞는지 확인한 뒤 entry 적용을 시작한다.

원자적 교체가 아닌 entry별 변경

envfs_load_data()는 이름을 목적 경로에 결합하고 각 파일을 O_TRUNC로 열거나 symlink를 변경한다. 뒤쪽 inode magic·open·write 오류로 중단돼도 앞선 파일을 되돌리는 rollback은 없다. ENV_FLAG_NO_OVERWRITE가 있고 기존 파일이 있으면 해당 entry는 건너뛴다.

반환값만으로 전부 성공했다고 판단하지 않는다

symlink 생성 오류는 로그를 남긴 뒤 순회를 계속하며 끝의 ret = 0에 의해 가려질 수 있다. 디렉터리 생성·close 결과도 모두 전파되지 않는다. short read/write 분기 일부는 -errno를 사용하므로 해당 반환값만으로 모든 entry의 적용 성공을 보증하지 않는다. 대상 파일과 로그를 함께 대조한다.

부팅 시 overlay 순서

load_environment()는 설정된 built-in default를 먼저 읽고 허용된 외부 envfs를 그 위에 적용한다. 이후 DT compatible overlay와 nvvar_load()가 이어진다. 외부 load의 반환값으로 이 initcall을 중단하지 않으므로 initcall의 0 반환은 외부 환경 적용 성공과 다르다.

구현을 읽을 때 놓치기 쉬운 부분

01

envfs는 key-value blob이 아니라 파일 tree image다

superblock magic·CRC와 전체 data CRC를 검사한 뒤 inode entry를 순회해 대상 directory에 파일과 symlink를 직접 적용한다. 개별 inode magic, mode, file length와 image 범위를 확인해야 한다.

entry name이 concat_path_file(dir, name)으로 대상 경로가 되는 지점을 확인한다. 외부 image를 신뢰할 수 있는지는 이 경로 처리와 별도로 검토한다.

02

default environment와 persistent overlay 순서를 본다

부팅의 startup.c는 built-in default를 먼저 load하고, 설정이 허용하면 외부 envfs를 같은 /env에 load한다. CRC 오류는 적용 전 반환하지만 entry 처리 중 오류에는 이전 파일 변경을 되돌리는 rollback이 없다.

같은 파일의 source와 최종 내용을 표시해 우선순위를 검증한다.

03

saveenv의 atomicity는 backend에 달려 있다

saveenv의 storage image 기록과 loadenv의 runtime 파일 적용은 서로 다른 실패 경로다. 저장 매체의 전원 차단 위험은 별도로 시험하고, load 과정의 파일별 변경을 원자적 교체로 설명하지 않는다.

write 중 reset 뒤 어느 copy가 선택되는지 반복 시험한다.

객체와 수명

대상만들어지는 시점유효 범위확인할 조건
envfs_superenvfs_load()의 stack함수 반환 전까지magic·header CRC·data size 확인
envfs image data buffersuperblock 확인 뒤 할당·읽기반환 경로에서 free전체 data CRC 확인 후 entry 적용
built-in default 파일부팅 초기화의 defaultenv_load()/env 안에서 후속 변경까지외부 envfs load보다 앞선 기본 layer
외부 entry의 대상 파일envfs_load_data()의 각 open(O_TRUNC)·write파일이 다시 수정될 때까지후반 오류에도 앞선 write rollback 없음
symlink entryenvfs_load_data()의 unlink·symlink다음 변경까지기존 경로를 바로 교체할 수 있음

실패 지점과 증상

#조건관찰되는 증상먼저 볼 단계
01superblock/data CRC 오류entry 적용 전 load 실패; 부팅 default 유지envfs_check_super/data
02inode magic 오류load 중단; 앞선 파일 변경 가능envfs_load_data
03후반 entry 쓰기 오류앞선 /env 파일만 바뀐 상태 가능envfs_load_data

로그가 끊긴 함수뿐 아니라 그 함수에 주소, 크기, 플래그를 전달한 앞 단계도 조사한다. 오류 처리 후 등록된 객체나 하드웨어 설정이 그대로 남아 있는지도 확인한다.

반환값과 실제 파일을 대조한다

자료확인할 차이
고정 버전의 environment.c·envfs-core.cCRC 전 실패와 entry 적용 후 실패, NO_OVERWRITE 분기
보드 설정과 startup.cbuilt-in default·외부 autoload·DT overlay·nvvar 순서
격리 시험 directory의 전후 파일 목록·내용앞서 바뀐 파일과 실패한 뒤쪽 entry를 구분
반환값과 symlink·write 오류 로그로그만 남고 최종 0으로 끝나는 오류를 별도 확인

직접 확인할 실험

  1. 01
    saveenv/loadenv 전후 envfs header 비교

    envfs superblock 진입 전후에 envfs image의 주소·크기·반환값과 timestamp를 함께 남긴다.

  2. 02
    CRC 오류 후 부팅 default 유지 확인

    data CRC 검증 진입 전후에 superblock/inodes의 주소·크기·반환값과 timestamp를 함께 남긴다.

  3. 03
    후반 entry 오류 때 앞선 파일 상태 확인

    envfs_load_data() 진입 전후에 runtime directory의 주소·크기·반환값과 timestamp를 함께 남긴다.

원문과 다음 글