نام (NAME)

wayvnc - کارساز VNC برای کامپوزیتورهای Wayland مبتنی بر wlroots.

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

wayvnc [گزینه‌ها] [address...]

گزینه‌ها (OPTIONS)

-a, --desktop

ضبط تمام خروجی‌ها.

-C, --config=<path>

انتخاب یک فایل پیکربندی.

-d, --disable-input

غیرفعال کردن تمام ورودی‌های از راه دور. این کار اجازه می‌دهد wayvnc بدون پشتیبانی کامپوزیتور از پروتکل‌های ماوس / صفحه‌کلید مجازی استفاده شود.

-D, --detached

راه‌اندازی به‌صورت جدا شده از کامپوزیتور. برای اتصال به یک کامپوزیتور دستور wayvncctl attach را اجرا کنید.

-f, --max-fps=<fps>

تنظیم محدودیت نرخ فریم (پیش‌فرض 30).

-F, --log-filter=<file>

تنظیم یک فیلتر گزارش.

-g, --gpu

فعال‌سازی قابلیت‌هایی که به GPU نیاز دارند.

-h, --help

دریافت راهنما.

-k, --keyboard=<layout>[-variant]

انتخاب چیدمان صفحه‌کلید. در صورت نیاز می‌توان variant را نیز اضافه کرد.

-L, --log-level

تنظیم سطح گزارش‌گیری. سطوح عبارتند از: error، warning، info، debug، trace و quiet.

-n, --name=<name>

تنظیم نام میزکار. پیش‌فرض: WayVNC

-o, --output=<name>

انتخاب خروجی برای ضبط.

-p, --show-performance

نمایش شمارنده‌های کارایی.

-r, --render-cursor

فعال‌سازی رندر نشانگر هم‌پوشان (overlay cursor).

-R, --disable-resizing

غیرفعال کردن تغییر اندازهٔ خودکار میزکار.

-s, --seat=<name>

انتخاب seat بر پایه نام.

-t, --transient-seat

ایجاد یک seat گذرا (transient) برای هر نشست کلاینت.

-T, --toplevel=<identifier>

ضبط یک toplevel.

-S, --socket=<path>

تنظیم مسیر سوکت کنترلی wayvnc. پیش‌فرض: $XDG_RUNTIME_DIR/wayvncctl یا /tmp/wayvncctl-$UID

-v, --verbose

نمایش جزئیات بیشتر. همانند تنظیم `--log-level=info`.

-V, --version

نمایش اطلاعات نسخه.

می‌توان چندین آدرس شنود را با افزودن آنها به فهرست آرگومان‌ها مشخص کرد.

برای یک آدرس شبکهٔ معمولی، شمارهٔ پورت را می‌توان با افزودن آن به آدرس با جداکنندهٔ : تعیین کرد؛ مانند: localhost:5901.

اگر پورت مشخص شده باشد، آدرس‌های IPv6 باید در کروشه قرار گیرند؛ مانند: [::]:5901.

انواع مختلف سوکت را می‌توان با قرار دادن نام نوع مربوطه به عنوان پیشوند آدرس همراه با یک : در میان آنها مشخص کرد؛ مانند unix:/tmp/wayvnc.sock. انواع سوکت عبارتند از: tcp، unix، fd، ws، ws-unix و ws-fd.

با نوع fd، می‌توانید یک سوکت از پیش متصل‌شده (bound) را برای شنود کارساز VNC ارسال کنید. توصیف‌گر فایل (file descriptor) یک مقدار عددی به ارث رسیده از فرایند والد wayvnc است. مثال: fd:42.

خانوادهٔ پیشوندهای ws تمام ارتباطات روی سوکت داده‌شده را با استفاده از فریم‌بندی WebSocket کپسوله‌سازی می‌کند. مثال: ws:0.0.0.0.

توضیحات (DESCRIPTION)

این یک کارساز VNC برای کامپوزیتورهای Wayland مبتنی بر wlroots است. این برنامه به یک نشست Wayland در حال اجرا متصل می‌شود، دستگاه‌های ورودی مجازی ایجاد می‌کند و یک نمایشگر منفرد را از طریق پروتکل RFB ارائه می‌دهد. نشست Wayland ممکن است بدون سر (headless) باشد، بنابراین امکان اجرای wayvnc بدون اتصال نمایشگر فیزیکی نیز وجود دارد.

چندین خروجی (MULTIPLE OUTPUTS)

اگر نشست Wayland شامل چندین خروجی باشد، تنها یکی از آنها ضبط خواهد شد. این خروجی به طور پیش‌فرض اولین خروجی خواهد بود، اما می‌توان آن را با آرگومان خط فرمان -o مشخص کرد. این آرگومان نام کوتاهی مانند eDP-1 یا DP-4 را می‌پذیرد. اجرای wayvnc در حالت پرگویی (-v) نام تمام خروجی‌ها را هنگام راه‌اندازی نمایش می‌دهد، یا می‌توانید آنها را در زمان اجرا از طریق دستور wayvncctl output-list پرس‌وجو کنید.

همچنین می‌توانید خروجی در حال ضبط را در لحظه از طریق دستور wayvncctl output-set تغییر دهید.

پیکربندی (CONFIGURATION)

دستور wayvnc فایل پیکربندی را در این مکان جستجو می‌کند:

~/$XDG_CONFIG_HOME/wayvnc/config

یا اگر $XDG_CONFIG_HOME تنظیم نشده باشد:

~/.config/wayvnc/config

نحو (SYNTAX)

فایل پیکربندی از جفت‌های کلید-مقدار تشکیل شده است که با یک علامت مساوی از هم جدا می‌شوند. فاصله‌های خالی در اطراف کلید یا مقدار بی‌اهمیت هستند و بخشی از کلید یا مقدار محسوب نمی‌شوند.

کلیدواژه‌ها (KEYWORDS)

address

آدرسی که کارساز باید به آن متصل شود، مانند 0.0.0.0 یا localhost.

certificate_file

مسیر فایل گواهی برای رمزنگاری. فقط زمانی اعمال می‌شود که enable_auth=true باشد.

enable_auth

فعال‌سازی احراز هویت و رمزنگاری. تنظیم این مقدار بر روی true نیازمند تنظیم certificate_file، private_key_file و password نیز هست. مقدار username اختیاری است و در صورت تنظیم نشدن، پیش‌فرض آن یک رشتهٔ خالی است.

enable_pam

استفاده از PAM برای احراز هویت. در صورت فعال بودن، PAM تنظیمات username و password را نادیده می‌گیرد. برخی روش‌های احراز هویت مانند DES با PAM کار نمی‌کنند.

password

انتخاب یک گذرواژه برای احراز هویت. زمانی که enable_auth تنظیم شده باشد و از enable_pam استفاده نشود، الزامی است.

port

پورتی که کارساز باید به آن متصل شود. پیش‌فرض 5900 است.

private_key_file

مسیر فایل کلید خصوصی برای رمزنگاری TLS. فقط زمانی اعمال می‌شود که enable_auth=true باشد.

relax_encryption

پس از احراز هویت کاربر، نیازی به رمزنگاری نباشد. این گزینه برخی انواع امنیتی مانند Apple Diffie-Hellman را فعال می‌کند.

rsa_private_key_file

مسیر فایل کلید خصوصی برای رمزنگاری RSA-AES. فقط زمانی اعمال می‌شود که enable_auth=true باشد.

username

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

allow_broken_crypto

اجازه دادن به استفاده از روش‌های رمزنگاری ناامن مانند احراز هویت DES. در صورت فعال بودن، کلاینت‌های قدیمی VNC که از انواع امنیتی مدرن پشتیبانی نمی‌کنند می‌توانند با استفاده از فیلد password احراز هویت شوند. تنها برای سازگاری با کلاینت‌های قدیمی در یک شبکهٔ مورد اعتماد استفاده شود.

use_relative_paths

نسبی کردن مسیرهای فایل نسبت به مکان فایل پیکربندی.

xkb_layout

چیدمان صفحه‌کلید برای جستجوی کد کلیدها.

پیش‌فرض: XKB_DEFAULT_LAYOUT یا پیش‌فرض سیستم.

xkb_model

مدل صفحه‌کلید که کدهای کلید و LEDها بر اساس آن تفسیر می‌شوند.

پیش‌فرض: "pc105"

xkb_options

فهرستی از گزینه‌ها با کاما جدا شده که از طریق آن، کاربر ترجیحات غیرمرتبط با چیدمان را تعیین می‌کند، مانند این که کدام کلید، کلید Compose باشد.

پیش‌فرض: XKB_DEFAULT_OPTIONS یا پیش‌فرض سیستم.

xkb_rules

فایل قوانین نحوهٔ تفسیر مقادیر فیلدهای مدل، چیدمان، گونه و گزینه‌ها را شرح می‌دهد.

پیش‌فرض: XKB_DEFAULT_RULES یا پیش‌فرض سیستم.

xkb_variant

گونهٔ صفحه‌کلید برای استفاده در جستجوی کد کلید.

پیش‌فرض: XKB_DEFAULT_VARIANT یا پیش‌فرض سیستم.

use_relative_paths=true
address=0.0.0.0
enable_auth=true
username=luser
password=p455w0rd
rsa_private_key_file=rsa_key.pem
private_key_file=tls_key.pem
certificate_file=tls_cert.pem

سوکت کنترلی WAYVNCCTL (WAYVNCCTL CONTROL SOCKET)

برای تسهیل تعامل و کنترل در زمان اجرا، wayvnc یک سوکت دامنه یونیکس (unix domain socket) در مسیر $XDG_RUNTIME_DIR/wayvncctl (یا در صورت عدم دسترسی، /tmp/wayvncctl-$UID) باز می‌کند. یک کلاینت می‌تواند متصل شده و برای پرس‌وجو و کنترل نمونه‌ی در حال اجرای wayvnc، پیام‌های IPC با قالب JSON مبادله کند.

دستورات IPC (IPC COMMANDS)

HELP

دستور help هنگامی که بدون هیچ پارامتری صادر شود، نام تمامی دستورات موجود را فهرست می‌کند.

اگر پارامتر اختیاری command با نام به یکی از این دستورات اشاره کند، داده‌های پاسخ شامل توضیحاتی دقیق درباره آن دستور و پارامترهایش خواهد بود.

EVENT-RECEIVE

دستور event-receive برای رویدادهای ناهمگام سرور ثبت‌نام می‌کند. برای جزئیات مربوط به قالب پیام رویداد به بخش EVENTS در زیر، و برای شرح تمامی رویدادهای ممکن سرور به بخش IPC EVENTS در زیر مراجعه کنید.

ثبت‌نام رویداد، برای تمامی رویدادهای موجود سرور ثبت‌نام می‌کند و دامنه آن تنها به اتصال فعلی محدود است. اگر یک کلاینت قطع و دوباره متصل شود، باید مجدداً برای رویدادها ثبت‌نام کند.

CLIENT-LIST

دستور client-list فهرستی از تمامی کلاینت‌های VNC که در حال حاضر به wayvnc متصل هستند را دریافت می‌کند.

CLIENT-DISCONNECT

دستور client-disconnect یک کلاینت VNC منفرد را قطع می‌کند.

پارامترها:

id

الزامی: شناسه (ID) کلاینت جهت قطع اتصال. این شناسه را می‌توان از دستور GET-CLIENTS یا دریافت رویداد CLIENT-CONNECTED به دست آورد.

SET-DESKTOP-NAME

دستور set-desktop-name نام میزکار ارسال‌شده به کلاینت‌های جدید را تغییر می‌دهد و نام را برای کلاینت‌های متصلی که از به‌روزرسانی نام میزکار پشتیبانی می‌کنند، به‌روزرسانی می‌کند.

پارامترها:

desktop-name

الزامی: نام میزکار.

OUTPUT-LIST

دستور output-list فهرستی از تمامی خروجی‌های شناخته‌شده برای wayvnc و اینکه آیا هر کدام در حال حاضر ضبط می‌شوند یا خیر را دریافت می‌کند.

OUTPUT-CYCLE

برای نمایشگرهای چندخروجی Wayland، دستور output-cycle خروجی‌ای که به طور فعال توسط wayvnc ضبط می‌شود را تغییر می‌دهد. اجرای یک‌باره این دستور، به خروجی در دسترس بعدی جابه‌جا می‌شود. اگر خروجی دیگری در دسترس نباشد، دوباره به خروجی اول برمی‌گردد.

OUTPUT-SET

برای نمایشگرهای چندخروجی Wayland، دستور output-set خروجی‌ای که به طور فعال توسط wayvnc ضبط می‌شود را بر اساس نام تغییر می‌دهد.

output-name=name

الزامی: نام خروجی بعدی جهت ضبط.

VERSION

دستور version اطلاعات نسخه را از نمونه در حال اجرای wayvnc پرس‌وجو می‌کند. همانند گزینه -V، داده‌های پاسخ شامل شماره نسخه‌های wayvnc و همچنین نسخه‌های مؤلفه‌های neatvnc و aml خواهد بود.

WAYVNC-EXIT

دستور wayvnc-exit تمام کلاینت‌ها را قطع کرده و wayvnc را می‌بندد.

CAPTURE_CHANGED

رویداد capture-changed زمانی ارسال می‌شود که خروجیِ در حال ضبط تغییر کند.

پارامترها:

output=...

نام خروجی‌ای که اکنون در حال ضبط است.

CLIENT-CONNECTED

رویداد client-connected زمانی ارسال می‌شود که یک کلاینت VNC جدید به wayvnc متصل شود.

پارامترها:

id=...

یک شناسه یکتا برای این کلاینت.

connection_count=...

تعداد کل کلاینت‌های VNC متصل، شامل این کلاینت.

address=...

نشانی IP این کلاینت. ممکن است null باشد.

username=...

نام کاربری استفاده‌شده برای احراز هویت این کلاینت. ممکن است null باشد.

CLIENT-DISCONNECTED

رویداد client-disconnected زمانی ارسال می‌شود که اتصال یک کلاینت VNC از wayvnc قطع شود.

پارامترها:

id=...

یک شناسه یکتا برای این کلاینت.

connection_count=...

تعداد کل کلاینت‌های VNC متصل، بدون احتساب این کلاینت.

address=...

نشانی IP این کلاینت. ممکن است null باشد.

username=...

نام کاربری استفاده‌شده برای احراز هویت این کلاینت. ممکن است null باشد.

قالب پیام IPC (IPC MESSAGE FORMAT)

ابزار خط فرمان wayvncctl(1) پیام‌های json ipc با قالب‌بندی درست ایجاد می‌کند، اما هر کلاینتی کار خواهد کرد. کلاینت ارتباط را آغاز کرده و یک یا چند شیء درخواست می‌فرستد که هر کدام یک شیء پاسخ متناظر دریافت خواهند کرد.

نکته: این قالب پیام ناپایدار است و ممکن است در چند نسخه بعدی دستخوش تغییرات اساسی شود.

REQUEST

شکل کلی یک پیام درخواست json-ipc به این صورت است:

{
	"method": "command-name",
	"id": 123,
	"params": {
		"key1": "value1",
		"key2": "value2",
	}
}

مقدار method نام دستوری است که باید اجرا شود. از متد help برای استعلام فهرستی از تمام نام‌های معتبر متدها استفاده کنید.

فیلد id اختیاری است و می‌تواند هر عدد یا رشته معتبر JSON باشد. در صورت ارائه، پاسخ این درخواست شامل همان مقدار id خواهد بود که کلاینت می‌تواند از آن برای هماهنگ کردن چندین درخواست و پاسخ استفاده کند.

شیء params پارامترهای اختیاری را برای هر متد فراهم می‌کند و در صورت خالی بودن می‌تواند حذف شود.

RESPONSE

{
	"id": 123,
	"code": 0,
	"data": {
		...
	}
}

اگر درخواست دارای id بود، پاسخ نیز مقدار یکسانی برای id خواهد داشت.

کد عددی code نشان‌دهنده چگونگی رسیدگی به درخواست است. مقدار 0 همیشه نشان‌دهنده موفقیت است. هر مقدار دیگری به معنی شکست بوده و بسته به متد مورد نظر متغیر است.

شیء data شامل داده‌های بازگشتی مخصوص هر متد است. این داده‌ها ممکن است داده‌های ساختاریافته در پاسخ به یک پرس‌وجو، یک رشته خطای ساده در صورت شکست درخواست باشند، یا اگر کد خطا به‌تنهایی کافی باشد، ممکن است به طور کامل حذف شود.

EVENTS

رویدادها پیام‌های ناهمگامی هستند که از یک سرور به تمام کلاینت‌های ثبت‌شده ارسال می‌شوند. قالب پیام با یک REQUEST یکسان است، اما فاقد فیلد "id" بوده و کلاینت نباید پاسخی ارسال کند.

پیام رویداد نمونه:

{
	"method": "event-name",
	"params": {
		"key1": "value1",
		"key2": "value2",
	}
}

برای دریافت هرگونه رویداد، کلاینت ابتدا باید با ارسال یک درخواست IPC از نوع event-receive برای دریافت آن‌ها ثبت‌نام کند. هنگامی که پاسخ موفقیت‌آمیز توسط سرور ارسال شد، کلاینت باید انتظار داشته باشد که پیام‌های رویداد ناهمگام در هر زمانی توسط سرور ارسال شوند، حتی میان یک درخواست و پاسخ مرتبط با آن.

متغیرهای محیطی زیر بر wayvnc تأثیر می‌گذارند:

WAYLAND_DISPLAY

نام نمایشگر Wayland را مشخص می‌کند که کامپوزیتوری که wayvnc باید به آن متصل شود، بر روی آن در حال اجرا است.

XDG_CONFIG_HOME

مکان فایل‌های پیکربندی را مشخص می‌کند.

XDG_RUNTIME_DIR

مکان پیش‌فرض را برای سوکت کنترلی wayvncctl مشخص می‌کند.

پرسش‌های متداول (FAQ)

خطای wayvnc مبنی بر عدم پشتیبانی از یک پروتکل

خطا ممکن است به این شکل باشد:

wl_registry@2: error 0: invalid version for global zxdg_output_manager_v1 (4): have 2, wanted 3
ERROR: ../src/main.c: 388: Screencopy protocol not supported by compositor. Exiting. Refer to FAQ section in man page.
ERROR: ../src/main.c: 1024: Failed to initialise wayland

این بدان معناست که کامپوزیتور Wayland شما پروتکل screencopy را پیاده‌سازی نکرده است و wayvnc با آن کار نخواهد کرد. پروتکل screencopy توسط کامپوزیتورهای مبتنی بر wlroots مانند Sway و Wayfire پیاده‌سازی شده است.

چگونه می‌توانم wayvnc را در حالت headless یا بر بستر یک نشست SSH اجرا کنم؟

پیش از اجرای کامپوزیتور، متغیرهای محیطی WLR_BACKENDS=headless و WLR_LIBINPUT_NO_DEVICES=1 را مقداردهی کرده و سپس wayvnc را به صورت عادی اجرا کنید.

چگونه می‌توانم کلید mod خود را از Sway به نشست میزکار از راه دور منتقل کنم؟

یک حالت (mode) تقریباً خالی در پیکربندی sway خود ایجاد کنید. به عنوان مثال:

mode passthrough {
	bindsym $mod+Pause mode default
}
bindsym $mod+Pause mode passthrough

این پیکربندی باعث می‌شود زمانی که کلیدهای $mod+Pause را فشار می‌دهید، تمامی کلیدهای میانبر به جز کلید بازگشت، غیرفعال شوند.

هنگام تایپ کردن همه نمادها نمایش داده نمی‌شوند. چگونه این مشکل را رفع کنم؟

سعی کنید چیدمان صفحه‌کلید را در wayvnc به چیدمانی تغییر دهید که بیشترین تطابق را با چیدمان مورد استفاده در سمت کلاینت دارد. نیازی به چیدمان کاملاً یکسان نیست، فقط کافی است شامل تمام نمادهایی باشد که استفاده می‌کنید.

چگونه کلید Compose را فعال کنم؟

مقدار "xkb_options=compose:menu" را در فایل پیکربندی تنظیم کنید. هر کلیدی که برای کار دیگری تخصیص داده نشده باشد کار خواهد کرد. فقط باید کلیدی وجود داشته باشد تا wayvnc بتواند آن را تطبیق دهد.

توسط Andri Yngvason <andri@yngvason.is> نگهداری می‌شود. سورس‌کدهای به‌روز را می‌توان در https://github.com/any1/wayvnc یافت و گزارش باگ‌ها یا وصله‌ها را می‌توان به ردیاب مشکلات (issue tracker) در GitHub ارسال کرد.

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

wayvncctl(1)