QEMU-GA(8)                           QEMU                           QEMU-GA(8)

نام (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

11.1.1                          August 28, 2026                     QEMU-GA(8)