百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
O

overlaybd

> 编程语言
开源

Overlaybd: 基于块的远程图像格式。containerd/accelerated-container-image 的存储后端。

385 stars0 点赞1 次浏览
访问官网GitHub

工具介绍

Overlaybd: 基于块的远程图像格式。containerd/accelerated-container-image 的存储后端。

Overlaybd

简体中文

Overlaybd (overlay block device) is a novel layering block-level image format, which is design for container, secure container and applicable to virtual machine. And it is an open-source implementation of paper DADI: Block-Level Image Service for Agile and Elastic Application Deployment. USENIX ATC'20".

Scaling up Without Slowing Down: Accelerating Pod Start Time. KubeCon+CloudNativeCon Europe 2024

Overlaybd is based on PhotonLibOS, which is a high-efficiency LibOS framework.

Overlaybd has 2 core component:

  • Overlaybd is a block-device based image format, provideing a merged view of a sequence of block-based layers as a virtual block device. The LBA lookup algorithm employs a linearized B+ tree and AVX-512 to optimize performance, significantly accelerating search speed up to 10X. Lookup Performance

  • Zfile is a compression file format which support seekalbe online decompression.

This repository is an implementation of overlaybd based on TCMU.

Overlaybd can be used as the storage backend of Accelerated Container Image, which is a solution of remote container image by fetching image data on-demand without downloading and unpacking the whole image before the container starts.

Benefits from the universality of block-device, overlaybd is also a widely applicable image format for most runtime, including qemu/kvm and any other runtime supporting block or scsi api.

Overlaybd is a non-core sub-project of containerd.

Setup

System Requirements

Overlaybd provides virtual block devices through TCMU, so the TCMU kernel module is required. TCMU is implemented in the Linux kernel and supported by most Linux distributions. For linux v6.0+, overlaybd can provides virtual block devices via UBLK.

Check and load the target_core_user module.

bash
modprobe target_core_user ## TCMU
modprobe ublk_drv ## UBLK, linux v6.0+ requires

Install From RPM/DEB

You may download our RPM/DEB packages form Release and install.

The binaries are install to /opt/overlaybd/bin/.

Run /opt/overlaybd/bin/overlaybd-tcmu and the log is stored in /var/log/overlaybd.log.

It is better to run overlaybd-tcmu as a service so that it can be restarted after unexpected crashes.

Build From Source

Requirements

To build overlaybd from source code, the following dependencies are required:

  • CMake >= 3.14

  • gcc/g++ >= 8

  • Libaio, libcurl, libnl3, glib2 and openssl runtime and development libraries.

    • CentOS 7/Fedora: sudo yum install libaio-devel libcurl-devel openssl-devel libnl3-devel libzstd-static e2fsprogs-devel
    • CentOS 8: sudo yum install libaio-devel libcurl-devel openssl-devel libnl3-devel libzstd-devel e2fsprogs-devel
    • Debian/Ubuntu: sudo apt install libcurl4-openssl-dev libssl-dev libaio-dev libnl-3-dev libnl-genl-3-dev libgflags-dev libzstd-dev libext2fs-dev pkg-config automake libtool # libgtest-dev // for test
    • Mariner/AzureLinux: sudo yum install libaio-devel libcurl-devel openssl-devel libnl3-devel e2fsprogs-devel glibc-devel libzstd-devel binutils ca-certificates-microsoft build-essential

Build

You need git to checkout the source code:

bash
git clone https://github.com/containerd/overlaybd.git
cd overlaybd
git submodule update --init

The whole project is managed by CMake. Binaries and resource files will be installed to /opt/overlaybd/.

bash
mkdir build
cd build
cmake .. # -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=true -DBUILD_TESTING=true
make -j
sudo make install

Considering some libcurl and libopenssl has API changes, if want to build a make-sured compatible version libcurl and openssl, and link to executable as static library.

Noticed that building libcurl and openssl depends on autoconf automake and libtool.

bash
cmake -D BUILD_CURL_FROM_SOURCE=1 ..

If you want to use the original libext2fs instead of our customized libext2fs.

bash
cmake -D ORIGIN_EXT2FS=1 ..

For more information about ORIGIN_EXT2FS go to USERSPACE_CONVERTOR.

If you want to use DSA hardware to accelerate CRC calculation.

bash
cmake -D ENABLE_DSA=1 ..

If you want to use avx512 to accelerate CRC calculation.

bash
cmake -D ENABLE_ISAL=1 ..

If you want to use QAT to accelerate compression/decompression.However, currently only the decompression part has been integrated. Since LZ4 is already a highly efficient compression algorithm, our tests show that QAT can only outperform the CPU at a 4KB block size and a batch size of 256 when the compression ratio significantly exceeds a threshold.

bash
cmake -D ENABLE_QAT=1 ..

For more information go to overlaybd/src/overlaybd/zfile/README.md.

If you want to build the ublk frontend (overlaybd-ublk), which exposes an image as /dev/ublkbN without going through TCMU/SCSI. It is built by default only when the kernel supports ublk (auto-detected from the ublk_drv module or the linux/ublk_cmd.h uapi header); force it either way with -D BUILD_UBLK_FRONTEND=on|off. Building it additionally requires autoconf, automake and libtool (liburing and libublksrv are fetched and built from source automatically).

bash
cmake -D BUILD_UBLK_FRONTEND=on ..

Running the ublk backend requires a kernel with the ublk_drv driver (mainline

= 6.0, or a distro kernel with ublk backported). For how to run images through overlaybd-ublk / overlaybd-ublkd, see the UBLK backend section of Standalone Usage.

Finally, setup a systemd service for overlaybd-tcmu backstore.

bash
sudo systemctl enable /opt/overlaybd/overlaybd-tcmu.service
sudo systemctl start overlaybd-tcmu

Configuration

overlaybd config

Default configure file overlaybd.json is installed to /etc/overlaybd/.

…
Field Description
logConfig.logLevel The log level for log file, 0 - DEBUG, 1 - INFO, 2 - WARN, 3 - ERROR
logConfig.logPath The path for log file, /var/log/overlaybd.log is the default value.
logConfig.logSizeMB The size limit for log file, in MB, 10 is default (10 MB).
logConfig.logRotateNum The rotate number for log file, 3 is default.
ioEngine IO engine used to open local files: psync 0, libaio 1, posix aio 2.
cacheConfig.cacheType Cache type used, file, ocf and download are supported.
cacheConfig.cacheDir The cache directory for remote image data.
cacheConfig.cacheSizeGB The max size of cache, in GB.
cacheConfig.refillSize The refill size from source, in byte. 262144 is default (256 KB).
gzipCacheConfig.enable Whether decompressed gzip file cache is enabled or not.
gzipCacheConfig.cacheDir The cache directory for decompressed gzip data.
gzipCacheConfig.cacheSizeGB The max size of cache, in GB.
gzipCacheConfig.refillSize The refill size from source, in byte. 262144 is default (256 KB).
credentialFilePath(legacy) The credential used for fetching images on registry. /opt/overlaybd/cred.json is the default value.
credentialConfig.mode Authentication mode for lazy-loading.
  • file means reading credential from credentialConfig.path.
  • http means sending an http request to credentialConfig.path
  • https means sending an https request to credentialConfig.path, with optional client certificate authentication and CA pinning
  • uds means sending the same http request as http mode, but over a Unix-domain socket at credentialConfig.path | | credentialConfig.path | credential file path or url which is determined by mode | | credentialConfig.client_cert_path | Optional. Path to the client certificate file (https mode). May contain the private key in the same PEM file. | | credentialConfig.client_key_path | Optional. Path to the client private key file (https mode). Only needed when the key is separate from the certificate. | | credentialConfig.server_ca_path | Optional. Path to the CA certificate used to verify the server (https mode). If omitted, the system CA bundle is used. When set, only this CA file is trusted. | | download.enable | Whether background downloading is enabled or not. | | download.delay | The seconds waiting to start downloading task after the overlaybd device launched. | | download.delayExtra | A random extra delay is attached to delay, avoiding too many tasks started at the same time. | | download.maxMBps | The speed limit in MB/s for a downloading task. | | download.blockSize | The download block size from source, in byte. 262144 is default (256 KB). | | p2pConfig.enable | Whether p2p proxy is enabled or not. | | p2pConfig.address | The proxy for p2p download, the format is localhost:/, depending on dadip2p.yaml | | exporterConfig.enable | whether or not create a server to show Prometheus metrics. | | exporterConfig.uriPrefix | URI prefix for export metrics. | | exporterConfig.port | port for http server to show metrics. | | exporterConfig.updateInterval | Time interval to update metrics in microseconds. | | enableAudit | Enable audit or not. | | enableThread | Enable overlaybd device run in seprate thread or not. Note cacheType should be ocf. false is default. | | auditPath | The path for audit file, /var/log/overlaybd-audit.log is the default value. | | registryFsVersion | registry client version, 'v1' libcurl based, 'v2' is photon http based. 'v2' is the default value. | | prefetchConfig.concurrency | Prefetch concurrency for reloading trace, 16 is default | | certConfig.certFile | The path for SSL/TLS client certificate file | | certConfig.keyFile | The path for SSL/TLS client key file | | userAgent | customized userAgent to identify HTTP request. default value is package version like 'overlaybd/1.1.14-6c44

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

C++blockdevicecontainer-imagesiscsi-targetremote-image

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言