QEMU-VNC(1) QEMU QEMU-VNC(1)

qemu-vnc - کارساز مستقل VNC برای QEMU

qemu-vnc [OPTION]...

qemu-vnc یک کارساز مستقل VNC است که از طریق رابط نمایشگر D-Bus (نمایشگر D-Bus <#dbus-display>) به یک نمونه در حال اجرای QEMU متصل می‌شود. این برنامه نمایشگر مهمان، ورودی، صدا، بریده‌دان و chardevهای کنسول سریال را بر بستر پروتکل VNC ارائه می‌دهد، و به کلاینت‌های VNC امکان می‌دهد بدون نیاز به ایجاد سوکت VNC توسط خود QEMU، با ماشین مجازی تعامل داشته باشند.

نمایش راهنما و خروج.
چاپ اطلاعات نسخه و خروج.
آدرس D-Bus جهت اتصال. در صورت عدم تعیین، qemu-vnc به گذرگاه نشست (session bus) متصل می‌شود.
توصیف‌کننده فایل (FD) مربوط به یک سوکت Unix به ارث‌رسیده برای اتصال نظیربه‌نظیر D-Bus به QEMU. این گزینه با --dbus-address و --bus-name ناسازگار (مانعة‌الجمع) است.
نام گذرگاه D-Bus مربوط به نمونه QEMU جهت اتصال. پیش‌فرض org.qemu است. هنگامی که یک --dbus-address سفارشی بدون نام گذرگاه داده شود، D-Bus نظیربه‌نظیر به کار گرفته می‌شود.
انتظار برای ظاهر شدن نام گذرگاه D-Bus. فقط برای اتصالات گذرگاه معتبر است.
الزام کلاینت‌های متصل‌شونده به احراز هویت با گذرواژه VNC. گذرواژه در زمان اجرا از طریق متد D-Bus به نام SetPassword تنظیم می‌شود (ببینید D-Bus VNC <>). کلاینت‌ها تا زمانی که گذرواژه‌ای تعیین نشده باشد قادر به اتصال نخواهند بود.

این گزینه هنگامی که گذرواژه اعتبارنامه‌ای systemd موجود باشد نادیده گرفته می‌شود، زیرا در این حالت احراز هویت با گذرواژه از قبل توسط password-secret فعال شده است.

آدرس شنود VNC با همان قالبی که در گزینه -vnc دستور QEMU استفاده می‌شود (پیش‌فرض localhost:0، یعنی درگاه TCP شماره 5900).
فعال‌سازی انتقال WebSocket روی آدرس داده‌شده. ADDR می‌تواند یک شماره درگاه یا جفت address:port باشد.
ایجاد یک شیء قابل ساخت توسط کاربر (user-creatable) در QEMU. آرگومان OBJDEF از همان نحو key=value مشابه گزینه -object در QEMU استفاده می‌کند. این گزینه می‌تواند چندین بار مشخص شود؛ برای مثال برای ایجاد اشیاء مجوزدهی که در --tls-authz به آن‌ها ارجاع داده شده، لازم است.
دایرکتوری حاوی اعتبارنامه‌های TLS x509 (ca-cert.pem، server-cert.pem، server-key.pem). در صورت تعیین، کارساز VNC از کلاینت‌های متصل‌شونده استفاده از TLS را الزامی خواهد کرد.
شناسه (ID) یک شیء QAuthZ که پیش‌تر با --object برای مجوزدهی گواهی کلاینت TLS ایجاد شده است. در صورت تعیین، اعتبارنامه‌های TLS با verify-peer=yes ساخته می‌شوند تا کلاینت‌های متصل‌شونده ملزم به ارائه یک گواهی معتبر باشند. پس از دست‌تکانی TLS، نام متمایز (Distinguished Name) گواهی کلاینت در برابر شیء مجوزدهی بررسی می‌شود. این گزینه نیازمند --tls-creds است.
الزام کلاینت به استفاده از SASL برای احراز هویت با کارساز VNC. انتخاب دقیق روش احراز هویت استفاده‌شده، از طریق فایل پیکربندی SASL سیستم/کاربر برای سرویس 'qemu' کنترل می‌شود. این فایل معمولاً در /etc/sasl2/qemu.conf قرار دارد. در صورت اجرای QEMU به عنوان یک کاربر غیرممتاز، می‌توان از متغیر محیطی SASL_CONF_PATH استفاده کرد تا مسیرهای جایگزین برای پیکربندی سرویس جستجو شوند. با وجود اینکه برخی از روش‌های احراز هویت SASL می‌توانند رمزنگاری داده‌ها را نیز فراهم کنند (مانند GSSAPI)، توصیه می‌شود که SASL همواره با تنظیمات 'tls' و 'x509' ترکیب شود تا استفاده از SSL و گواهی‌های کارساز ممکن گردد. این کار رمزنگاری داده‌ها را تضمین کرده و از فاش شدن اعتبارنامه‌های احراز هویت جلوگیری می‌کند. برای جزئیات مربوط به استفاده از احراز هویت SASL، بخش امنیت VNC (<#vnc-security>) را در راهنمای کاربری شبیه‌سازی سیستم (System Emulation Users Guide) ببینید.
--sasl-authz=ID
شناسه (ID) یک شیء QAuthZ که پیش‌تر با --object برای مجوزدهی نام کاربری SASL ایجاد شده است. پس از احراز هویت موفقیت‌آمیز SASL، نام کاربری احراز هویت‌شده در برابر شیء مجوزدهی بررسی می‌شود. در صورت رد شدن بررسی، اتصال کلاینت قطع می‌شود. این گزینه نیازمند --sasl است.
تنظیم سیاست اشتراک‌گذاری نمایشگر. آرگومان POLICY یکی از مقادیر allow-exclusive، force-shared، یا ignore است.

سیاست allow-exclusive به کلاینت‌ها امکان می‌دهد تا درخواست دسترسی انحصاری کنند. طبق پیشنهاد ارائه‌شده در مشخصات RFB، این کار با قطع سایر اتصالات پیاده‌سازی می‌شود. اتصال هم‌زمان چند کلاینت نیازمند آن است که تمام کلاینت‌ها درخواست نشست اشتراکی داشته باشند (سوئیچ -shared در vncviewer). این مقدار پیش‌فرض است.

سیاست force-shared دسترسی انحصاری کلاینت را غیرفعال می‌سازد. این حالت برای نشست‌های میزکار اشتراکی مفید است؛ جایی که مایل نیستید فراموش کردن تعیین -shared توسط یک کاربر، اتصال دیگران را قطع کند.

سیاست ignore پرچم اشتراک‌گذاری (shared) را کاملاً نادیده می‌گیرد و به همه اجازه می‌دهد بدون قید و شرط متصل شوند. این رفتار با مشخصات RFB سازگار نیست اما رفتار سنتی QEMU به شمار می‌رود.

نام نوع chardev جهت ارائه به عنوان کنسول متنی VNC. این گزینه می‌تواند چندین بار مشخص شود تا چندین chardev در دسترس قرار گیرند. در صورت عدم تعیین، مقادیر پیش‌فرض org.qemu.console.serial.0 و org.qemu.monitor.hmp.0 استفاده می‌شوند.
عدم ارائه هیچ‌یک از chardevها به عنوان کنسول متنی. این گزینه فهرست پیش‌فرض chardev و تمامی گزینه‌های --vt-chardev را لغو می‌کند.
-k LAYOUT, --keyboard-layout=LAYOUT چیدمان صفحه‌کلید (مانند en-us). جهت ترجمهٔ کدهای کلید (key-code) به کارساز VNC فرستاده می‌شود.
فعال‌سازی روش‌های فشرده‌سازی با اتلاف (gradient، JPEG و...). در صورت فعال بودن این گزینه، کلاینت VNC ممکن است بسته به تنظیمات کدگذاری خود، به‌روزرسانی‌های بافرفریم را با اتلاف دریافت کند. فعال کردن این گزینه می‌تواند به بهای افت کیفیت، پهنای باند قابل توجهی را صرفه‌جویی کند.
غیرفعال‌سازی کدگذاری‌های انطباقی. کدگذاری‌های انطباقی به‌طور پیش‌فرض فعال هستند. یک کدگذاری انطباقی تلاش می‌کند بخش‌هایی از صفحه را که مکرراً به‌روزرسانی می‌شوند شناسایی کرده و به‌روزرسانی‌های این نواحی را با استفاده از یک کدگذاری با اتلاف (مانند JPEG) ارسال کند. این قابلیت هنگام پخش ویدیو برای کاهش مصرف پهنای باند بسیار کاربردی است. غیرفعال‌سازی کدگذاری‌های انطباقی، رفتار ایستا و اولیهٔ کدگذاری‌هایی مانند Tight را بازیابی می‌کند.
مشخص کردن گزینه‌های ردیابی (trace).

[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 کامپایل شده باشد.

اجرای QEMU با بک‌اند نمایش D-Bus:

qemu-system-x86_64 -display dbus ...

سپس متصل کردن qemu-vnc:

qemu-vnc

اکنون یک کلاینت VNC می‌تواند به localhost:5900 متصل شود.

برای شنود روی درگاهی متفاوت همراه با TLS:

qemu-vnc --vnc-addr localhost:1 --tls-creds /etc/pki/qemu-vnc

برای الزامی کردن TLS همراه با اعتبارسنجی گواهی کلاینت:

qemu-vnc --object authz-list-file,id=auth0,filename=/etc/qemu/vnc.acl,refresh=on \
         --tls-creds /etc/pki/qemu-vnc --tls-authz auth0

برای فعال‌سازی احراز هویت SASL با TLS:

qemu-vnc --tls-creds /etc/pki/qemu-vnc --sasl

دو راه برای فعال‌سازی احراز هویت با گذرواژه VNC وجود دارد:

1.
پرچم --password -- آغاز qemu-vnc با --password و سپس تنظیم گذرواژه در زمان اجرا با استفاده از متد SetPassword در D-Bus. تا زمانی که گذرواژه‌ای تعیین نشود، کلاینت‌ها رد خواهند شد.
2.
اعتبارنامه‌های systemd -- اگر متغیر محیطی CREDENTIALS_DIRECTORY تنظیم شده باشد (systemd.exec(5) را ببینید) و شامل فایلی با نام vnc-password باشد، کارساز VNC به‌طور خودکار از محتویات آن فایل به عنوان گذرواژه استفاده خواهد کرد. در این حالت نیازی به پرچم --password نیست.

qemu-vnc یک رابط D-Bus را برای مدیریت و پایش اتصالات VNC ارائه می‌دهد. برای مرجع کامل رابط به D-Bus VNC <> مراجعه کنید.

qemu(1), D-Bus display <>, D-Bus VNC <>, The RFB Protocol https://github.com/rfbproto/rfbproto

2026, The QEMU Project Developers

August 28, 2026 11.1.1