نام (NAME)

qemu-ga - عامل مهمان QEMU

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

qemu-ga [OPTIONS]

توضیحات (DESCRIPTION)

عامل مهمان QEMU یک دیمن است که برای اجرا در داخل ماشین‌های مجازی در نظر گرفته شده است. این عامل به میزبان هایپروایزر اجازه می‌دهد تا عملیات مختلفی را در سیستم مهمان انجام دهد، از قبیل:

دریافت اطلاعات از سیستم مهمان
تنظیم زمان سیستم مهمان
خواندن/نوشتن فایل
همگام‌سازی و انجماد سیستم‌های فایل
تعلیق سیستم مهمان
پیکربندی مجدد پردازنده‌های محلی مهمان
تنظیم گذرواژه کاربر
...

دستور qemu-ga در هنگام راه‌اندازی یک فایل پیکربندی سیستم (به‌طور پیش‌فرض در مسیر /etc/qemu/qemu-ga.conf) را می‌خواند، سپس باقی گزینه‌های پیکربندی موجود در خط فرمان را پردازش می‌کند. برای کلیدهای یکسان، آخرین گزینه اولویت دارد، اما فهرست‌ها با یکدیگر تجمیع می‌شوند (برای قالب فایل پیکربندی به بخش زیر مراجعه کنید).

اگر فهرستی از RPCهای مجاز در پیکربندی تعریف شده باشد، آنگاه تمام RPCها به‌طور پیش‌فرض مسدود خواهند شد، به‌جز مواردی که در فهرست مجاز قرار دارند.

اگر فهرستی از RPCهای مسدودشده در پیکربندی تعریف شده باشد، آنگاه تمام RPCها به‌طور پیش‌فرض مجاز خواهند بود، به‌جز مواردی که در فهرست مسدودشده قرار دارند.

اگر هر دو فهرست RPCهای مجاز و مسدودشده در پیکربندی تعریف شده باشند، ابتدا تمام RPCها به‌طور پیش‌فرض مسدود می‌شوند، سپس فهرست مجاز اعمال می‌گردد و پس از آن فهرست مسدودشده اعمال خواهد شد.

در زمانی که سیستم‌های فایل منجمد هستند، بدون در نظر گرفتن آنچه در پیکربندی عمومی اعلام شده است، تمامی RPCها به‌جز یک مجموعه امن تعیین‌شده مسدود خواهند شد.

گزینه‌ها (OPTIONS)

-c, --config=PATH: مسیر فایل پیکربندی (پیش‌فرض /etc/qemu/qemu-ga.conf است، مگر اینکه توسط متغیر محیطی QGA_CONF بازنویسی شود).

-m, --method=METHOD: روش انتقال: یکی از مقادیر unix-listen، virtio-serial، یا isa-serial، یا vsock-listen (virtio-serial مقدار پیش‌فرض است).

-p, --path=PATH: مسیر دستگاه/سوکت (پیش‌فرض برای virtio-serial برابر با /dev/virtio-ports/org.qemu.guest_agent.0 و پیش‌فرض برای isa-serial برابر با /dev/ttyS0 است). آدرس‌های سوکت برای vsock-listen به صورت <cid>:<port> نوشته می‌شوند.

-l, --logfile=PATH: تنظیم مسیر فایل ثبت لاگ (پیش‌فرض stderr است).

-f, --pidfile=PATH: مشخص کردن فایل pid (پیش‌فرض /var/run/qemu-ga.pid است).

-F, --fsfreeze-hook=PATH: فعال‌سازی هوک fsfreeze. یک آرگومان اختیاری می‌پذیرد که اسکریپت مورد نظر برای اجرا هنگام انجماد/ذوب (freeze/thaw) را مشخص می‌کند. اسکریپت بر این اساس با آرگومان‌های 'freeze'/'thaw' فراخوانی خواهد شد (پیش‌فرض /etc/qemu/fsfreeze-hook است). در صورت استفاده از -F با یک آرگومان، پس از -F فاصله قرار ندهید (برای مثال: -F/var/run/fsfreezehook.sh).

-t, --statedir=PATH: مشخص کردن دایرکتوری ذخیره اطلاعات وضعیت (تنها مسیرهای مطلق، پیش‌فرض /var/run است).

-v, --verbose: ثبت اطلاعات اشکال‌زدایی بیشتر در لاگ.

-V, --version: چاپ اطلاعات نسخه و خروج.

-d, --daemon: تبدیل به دیمن پس از راه‌اندازی (جدا شدن از ترمینال).

-b, --block-rpcs=LIST: فهرستی از RPCها برای غیرفعال‌سازی که با کاما از هم جدا شده‌اند (بدون فاصله، از --block-rpcs=help برای فهرست کردن RPCهای موجود استفاده کنید).

-a, --allow-rpcs=LIST: فهرستی از RPCها برای فعال‌سازی که با کاما از هم جدا شده‌اند (بدون فاصله، از --allow-rpcs=help برای فهرست کردن RPCهای موجود استفاده کنید).

-D, --dump-conf: تخلیه پیکربندی در قالبی سازگار با qemu-ga.conf و خروج.

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

فایل‌ها (FILES)

ساختار نحوی فایل پیکربندی qemu-ga.conf از مشخصات دسکتاپ اینتری (Desktop Entry Specification) پیروی می‌کند؛ در اینجا خلاصه‌ای گذرا آمده است: این فایل از گروه‌هایی از جفت‌های کلید-مقدار تشکیل شده است که با کامنت‌ها درآمیخته‌اند.

# qemu-ga configuration sample
[general]
daemonize = 0
pidfile = /var/run/qemu-ga.pid
verbose = 0
method = virtio-serial
path = /dev/virtio-ports/org.qemu.guest_agent.0
statedir = /var/run

فهرست کلیدها از گزینه‌های خط فرمان پیروی می‌کند:

کلید (Key)	نوع کلید (Key type)
daemon	بولی (boolean)
method	رشته (string)
path	رشته (string)
logfile	رشته (string)
pidfile	رشته (string)
fsfreeze-hook	رشته (string)
statedir	رشته (string)
verbose	بولی (boolean)
block-rpcs	فهرست رشته (string list)
allow-rpcs	فهرست رشته (string list)

همچنین ببینید (SEE ALSO)

qemu(1)

نویسنده (AUTHOR)

Michael Roth <mdroth@linux.vnet.ibm.com>

حق نشر (COPYRIGHT)

2026, The QEMU Project Developers