QEMU-STORAGE-DAEMON(1)

QEMU

QEMU-STORAGE-DAEMON(1)

نام (NAME)

qemu-storage-daemon - دیمن ذخیره‌سازی QEMU

خلاصه دستور (SYNOPSIS)

qemu-storage-daemon [گزینه‌ها]

توضیحات (DESCRIPTION)

ابزار qemu-storage-daemon قابلیت‌های تصویر دیسک را از QEMU، qemu-img و qemu-nbd در قالب یک فرایند طولانی‌مدت فراهم می‌کند که از طریق دستورات QMP و بدون نیاز به اجرای یک ماشین مجازی کنترل می‌شود. این ابزار می‌تواند تصاویر دیسک را برون‌ریزی (export) کند، عملیات کارهای بلوکی را اجرا نماید، و سایر عملیات مربوط به دیسک را انجام دهد. این دیمن از طریق یک دیده‌بان (monitor) پروتکل QMP و پیکربندی اولیه از خط فرمان کنترل می‌شود.

این دیمن زیرمجموعه زیر از ویژگی‌های QEMU را ارائه می‌دهد:

گره‌های بلوکی (Block nodes)
کارهای بلوکی (Block jobs)
برون‌ریزی‌های بلوکی (Block exports)
گروه‌های کنترل نرخ (Throttle groups)
دستگاه‌های نویسه‌ای (Character devices)
رمزنگاری و اسرار (Crypto and secrets)
پروتکل QMP
رشته‌های ورودی/خروجی (IOThreads)

دستورات را می‌توان از طریق یک اتصال پروتکل دیده‌بان QEMU (یا همان QMP) ارسال کرد. برای شرح دستورات، صفحه راهنمای qemu-storage-daemon-qmp-ref(7) را ببینید.

این دیمن تا زمانی که با استفاده از دستور QMP با نام quit یا سیگنال‌های SIGINT/SIGHUP/SIGTERM متوقف شود، به کار خود ادامه می‌دهد.

هشدار: هرگز تصاویری را که توسط یک ماشین مجازی در حال اجرا یا هر فرایند دیگری استفاده می‌شوند تغییر ندهید؛ این کار ممکن است تصویر دیسک را تخریب کند. همچنین، آگاه باشید که پرس‌وجو از تصویری که توسط فرایند دیگری در حال تغییر است، ممکن است با وضعیتی ناسازگار مواجه شود.

گزینه‌ها (OPTIONS)

گزینه‌های استاندارد:

-h, --help: نمایش راهنما و خروج

-V, --version: نمایش اطلاعات نسخه و خروج

-T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]: مشخص کردن گزینه‌های ردگیری (tracing).
[enable=]PATTERN

رویدادهای منطبق با PATTERN (نام یک رویداد یا یک الگوی تطبیق globbing) را فوراً فعال می‌کند. این گزینه تنها در صورتی در دسترس است که QEMU با یکی از پس‌زمینه‌های ردگیری simple، log یا ftrace کامپایل شده باشد. برای تعیین چندین رویداد یا الگو، گزینه -trace را چندین بار مشخص کنید.

از -trace help برای چاپ فهرستی از نام‌های نقاط ردگیری استفاده کنید.

events=FILE

رویدادهای فهرست‌شده در FILE را فوراً فعال می‌کند. فایل باید در هر خط شامل یک نام رویداد (همان‌طور که در فایل trace-events-all فهرست شده) باشد؛ الگوهای globbing نیز پذیرفته می‌شوند. این گزینه تنها در صورتی در دسترس است که QEMU با پس‌زمینه ردگیری simple، log یا ftrace کامپایل شده باشد.

file=FILE

خروجی‌های ردگیری را در FILE ثبت (log) می‌کند. این گزینه تنها در صورتی در دسترس است که QEMU با پس‌زمینه ردگیری simple کامپایل شده باشد.

--blockdev BLOCKDEVDEF: یک تعریف گره بلوکی است. برای شرح ویژگی‌های گره بلوکی صفحه راهنمای qemu(1) و برای شرح پارامترهای مختص درایور صفحه راهنمای qemu-block-drivers(7) را ببینید.

--chardev CHARDEVDEF: یک تعریف دستگاه نویسه‌ای است. برای شرح ویژگی‌های دستگاه نویسه‌ای صفحه راهنمای qemu(1) را ببینید. یک تعریف متداول دستگاه نویسه‌ای، یک سوکت دامنه یونیکس (UNIX domain socket) را پیکربندی می‌کند:

--chardev socket,id=char1,path=/var/run/qsd-qmp.sock,server=on,wait=off

--export [type=]nbd,id=<id>,node-name=<node-name>[,name=<export-name>][,writable=on|off][,bitmap=<name>]

--export [type=]vhost-user-blk,id=<id>,node-name=<node-name>,addr.type=unix,addr.path=<socket-path>[,writable=on|off][,logical-block-size=<block-size>][,num-queues=<num-queues>]

--export [type=]vhost-user-blk,id=<id>,node-name=<node-name>,addr.type=fd,addr.str=<fd>[,writable=on|off][,logical-block-size=<block-size>][,num-queues=<num-queues>]

--export [type=]fuse,id=<id>,node-name=<node-name>,mountpoint=<file>[,growable=on|off][,writable=on|off][,allow-other=on|off|auto]

--export [type=]vduse-blk,id=<id>,node-name=<node-name>,name=<vduse-name>[,writable=on|off][,num-queues=<num-queues>][,queue-size=<queue-size>][,logical-block-size=<block-size>][,serial=<serial-number>]

یک تعریف برون‌ریزی بلوکی است. node-name گره بلوکی است که باید برون‌ریزی شود. writable مشخص می‌کند که آیا برون‌ریزی اجازه درخواست‌های نوشتن برای تغییر داده را می‌دهد یا خیر (پیش‌فرض off است).

نوع برون‌ریزی nbd نیازمند --nbd-server است (در زیر ببینید). name نام برون‌ریزی NBD است (اگر مشخص نشود، مقدار پیش‌فرض آن همان node-name داده‌شده خواهد بود). bitmap نام یک نگاشت بیتی کثیف (dirty bitmap) قابل دسترس از گره بلوکی است، تا کلاینت NBD بتواند از NBD_OPT_SET_META_CONTEXT همراه با نام زمینه فراداده "qemu:dirty-bitmap:BITMAP" برای بررسی نگاشت بیتی استفاده کند.

نوع برون‌ریزی vhost-user-blk یک نشانی سوکت vhost-user را دریافت می‌کند که از طریق آن اتصالات ورودی را می‌پذیرد. هم addr.type=unix,addr.path=<socket-path> برای سوکت‌های دامنه یونیکس و هم addr.type=fd,addr.str=<fd> برای انتقال توصیف‌گر فایل (file descriptor passing) پشتیبانی می‌شوند. logical-block-size اندازه بلوک منطقی را بر حسب بایت مشخص می‌کند (پیش‌فرض 512 است). num-queues تعداد virtqueueها را تنظیم می‌کند (پیش‌فرض 1 است).

نوع برون‌ریزی fuse یک نقطه اتصال (mount point) دریافت می‌کند که باید یک فایل معمولی باشد و گره بلوکی مشخص‌شده روی آن برون‌ریزی می‌شود. آن فایل تغییر نخواهد کرد، بلکه تا زمانی که برون‌ریزی فعال است صرفاً به نظر می‌رسد که محتوای گره بلوکی را دارد (دقیقاً مشابه اینکه سوار کردن (mount) یک فایل‌سیستم روی یک دایرکتوری، محتوای آن دایرکتوری را تغییر نمی‌دهد و تنها در زمان سوار بودن فایل‌سیستم محتوای متفاوتی را نشان می‌دهد). در نتیجه، برنامه‌هایی که فایل مورد نظر را قبل از فعال شدن برون‌ریزی باز کرده‌اند، همچنان محتوای اصلی آن را خواهند دید. اگر growable تنظیم شده باشد، نوشتن فراتر از انتهای فایل برون‌ریزی‌شده، اندازه گره بلوکی را متناسب با آن افزایش می‌دهد. گزینه allow-other کنترل می‌کند که آیا کاربرانی غیر از کاربر اجراکننده فرایند مجاز به دسترسی به برون‌ریزی هستند یا خیر. توجه داشته باشید که فعال‌سازی این گزینه به عنوان یک کاربر غیر ریشه (non-root)، نیازمند فعال‌سازی گزینه user_allow_other در فایل پیکربندی سراسری fuse.conf است. تنظیم allow-other روی auto (پیش‌فرض) سعی در فعال کردن این گزینه دارد و در صورت بروز خطا به غیرفعال کردن آن بازمی‌گردد.

نوع برون‌ریزی vduse-blk یک name (که باید در سراسر میزبان یکتا باشد) را برای ساخت دستگاه VDUSE دریافت می‌کند. num-queues تعداد virtqueueها را تنظیم می‌کند (پیش‌فرض 1 است). queue-size اندازه جدول توصیف‌گر virtqueue را تنظیم می‌کند (پیش‌فرض 256 است).

دستگاه VDUSE ساخته‌شده سپس باید با استفاده از دستور vdpa(8) از پروژه iproute2 به گذرگاه vDPA افزوده شود:

# vdpa dev add name <id> mgmtdev vduse

این دستگاه بعداً می‌تواند به شکل زیر از گذرگاه vDPA حذف شود:

# vdpa dev del <id>

برای اطلاعات بیشتر در مورد ضمیمه کردن دستگاه‌های vDPA به میزبان با virtio_vdpa.ko یا اتصال آن‌ها به سیستم‌های میهمان با vhost_vdpa.ko، پیوند https://vdpa-dev.gitlab.io را ببینید.

برای اطلاعات بیشتر درباره VDUSE، پیوند https://docs.kernel.org/userspace-api/vduse.html را ببینید.

--monitor MONITORDEF تعریف یک مانیتور QMP است. برای شرح ویژگی‌های مانیتور QMP به صفحهٔ راهنمای qemu(1) مراجعه کنید. یک تعریف متداول مانیتور QMP، مانیتوری را روی دستگاه نویسه‌ای char1 پیکربندی می‌کند:

--monitor chardev=char1

--nbd-server addr.type=inet,addr.host=<host>,addr.port=<port>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>]
--nbd-server addr.type=unix,addr.path=<path>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>]
--nbd-server addr.type=fd,addr.str=<fd>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>]: سروری برای برون‌ریزی‌های NBD است. هر دو سوکت TCP و دامنه یونیکس (UNIX domain) پشتیبانی می‌شوند. سوکت شنود (listen socket) می‌تواند از طریق ارسال توصیف‌گر فایل (file descriptor passing) فراهم شود (مثال‌های زیر را ببینید). رمزنگاری TLS را می‌توان با استفاده از اسرار --object tls-creds-* و authz-* پیکربندی کرد (به زیر مراجعه کنید).
برای پیکربندی یک سرور NBD روی مسیر سوکت دامنه یونیکس /var/run/qsd-nbd.sock:

--nbd-server addr.type=unix,addr.path=/var/run/qsd-nbd.sock

--object help
--object <type>,help
--object <type>[,<property>=<value>...]: تعریف یک شیء قابل ایجاد توسط کاربر در QEMU است. فهرست کردن انواع شیء با help و فهرست کردن ویژگی‌های شیء با <type>,help انجام می‌شود. برای شرح ویژگی‌های شیء به صفحهٔ راهنمای qemu(1) مراجعه کنید.

--pidfile PATH: مسیر فایلی است که دیمن شناسه فرایند (pid) خود را در آن می‌نویسد. این قابلیت به اسکریپت‌ها اجازه می‌دهد با ارسال یک سیگنال، دیمن را متوقف کنند:

$ kill -SIGTERM $(<path/to/qsd.pid)

یک قفل فایل روی این فایل اعمال می‌شود تا تنها یک نمونه از دیمن بتواند با یک مسیر فایل pid مشخص اجرا شود. دیمن هنگام خاتمه، فایل pid خود را حذف (unlink) می‌کند.

فایل pid پس از ایجاد chardevها، صادرات (exports) و سرورهای NBD، اما قبل از پذیرش اتصالات نوشته می‌شود. زمانی که فایل pid نوشته شود، دیمن با موفقیت راه‌اندازی شده است و کلاینت‌ها می‌توانند شروع به اتصال کنند.

--daemonize: فرایند را به یک دیمن تبدیل می‌کند (اجرا در پس‌زمینه). فرایند والد پس از تکمیل راه‌اندازی (یعنی پس از اینکه فایل pid نوشته شد یا قرار بود نوشته شود) یا در صورت بروز خطا، خارج خواهد شد. کد خروج آن نشان‌دهنده موفقیت یا شکست فرایند فرزند در راه‌اندازی است.

مثال‌ها (EXAMPLES)

راه‌اندازی دیمن با سوکت مانیتور QMP به نام qmp.sock تا کلاینت‌ها بتوانند دستورات QMP را اجرا کنند:

$ qemu-storage-daemon \
    --chardev socket,path=qmp.sock,server=on,wait=off,id=char1 \
    --monitor chardev=char1

راه‌اندازی دیمن از طریق پایتون با سوکت مانیتور QMP با استفاده از ارسال توصیف‌گر فایل (file descriptor passing)، به طوری که نیازی به انتظار فعال (busy wait) برای در دسترس قرار گرفتن مانیتور QMP نباشد:

#!/usr/bin/env python3
import subprocess
import socket
sock_path = '/var/run/qmp.sock'
with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as listen_sock:
    listen_sock.bind(sock_path)
    listen_sock.listen()
    fd = listen_sock.fileno()
    subprocess.Popen(
        ['qemu-storage-daemon',
         '--chardev', f'socket,fd={fd},server=on,id=char1',
         '--monitor', 'chardev=char1'],
        pass_fds=[fd],
    )
# listen_sock was automatically closed when leaving the 'with' statement
# body. If the daemon process terminated early then the following connect()
# will fail with "Connection refused" because no process has the listen
# socket open anymore. Launch errors can be detected this way.
qmp_sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
qmp_sock.connect(sock_path)
...QMP interaction...

همین رویکرد ایجاد سوکت با گزینه‌های --nbd-server addr.type=fd,addr.str=<fd> و --export type=vhost-user-blk,addr.type=fd,addr.str=<fd> نیز کار می‌کند.

برون‌ریزی فایل تصویر خام disk.img روی سوکت دامنه یونیکس NBD به نام nbd.sock:

$ qemu-storage-daemon \
    --blockdev driver=file,node-name=disk,filename=disk.img \
    --nbd-server addr.type=unix,addr.path=nbd.sock \
    --export type=nbd,id=export,node-name=disk,writable=on

برون‌ریزی یک فایل تصویر qcow2 با نام disk.qcow2 به عنوان یک دستگاه vhost-user-blk روی سوکت دامنه یونیکس vhost-user-blk.sock:

$ qemu-storage-daemon \
    --blockdev driver=file,node-name=file,filename=disk.qcow2 \
    --blockdev driver=qcow2,node-name=qcow2,file=file \
    --export type=vhost-user-blk,id=export,addr.type=unix,addr.path=vhost-user-blk.sock,node-name=qcow2

برون‌ریزی یک فایل تصویر qcow2 با نام disk.qcow2 از طریق FUSE بر روی خودش، تا بدین ترتیب فایل تصویر دیسک به عنوان یک تصویر خام (raw) ظاهر شود:

$ qemu-storage-daemon \
    --blockdev driver=file,node-name=file,filename=disk.qcow2 \
    --blockdev driver=qcow2,node-name=qcow2,file=file \
    --export type=fuse,id=export,node-name=qcow2,mountpoint=disk.qcow2,writable=on

qemu(1), qemu-block-drivers(7), qemu-storage-daemon-qmp-ref(7)

کپی‌رایت و تکثیر (COPYRIGHT)

2026، توسعه‌دهندگان پروژه QEMU

August 28, 2026

11.1.1