waypipe(1) General Commands Manual waypipe(1)

waypipe - یک پروکسی شفاف برای برنامه‌های Wayland

waypipe [options...] ssh [ssh options] destination command...

waypipe [options...] client
waypipe [options...] server -- command...
waypipe bench
waypipe [--version] [-h, --help]

[options...] = [-c, --compress C] [-d, --debug] [-n, --no-gpu] [-o, --oneshot] [-s, --socket S] [--display D] [--drm-node R] [--remote-node R] [--ssh-bin R] [--remote-bin R] [--remote-socket S] [--login-shell] [--threads T] [--title-prefix P] [--unlink-socket] [--video V] [--vsock] [--secctx S] [--xwls]

ابزار Waypipe یک پروکسی برای کلاینت‌های Wayland است که هدف آن پشتیبانی از رفتاری مشابه با ssh -X می‌باشد.

افزودن پیشوند به دستور ssh ... برای تبدیل شدن به waypipe ssh ... به طور خودکار waypipe را هم به صورت محلی و هم از راه دور اجرا می‌کند، و دستور ssh را به گونه‌ای تغییر می‌دهد که هدایت (forwarding) میان این دو نمونه از waypipe برقرار شود. نمونهٔ دوردست مانند یک کامپوزیتور Wayland عمل خواهد کرد و به برنامه‌های Wayland که از راه دور اجرا می‌شوند اجازه می‌دهد تا در سیستم محلی نمایش داده شوند.

هنگامی که به عنوان waypipe client اجرا شود، یک سوکت (به طور پیش‌فرض در /tmp/waypipe-client.sock) باز کرده و به کامپوزیتور محلی Wayland متصل می‌شود و تمامی برنامه‌های Wayland را که از طریق سوکت توسط یک نمونهٔ متناظر waypipe server متصل شده‌اند هدایت می‌کند.

هنگامی که به عنوان waypipe server اجرا شود، دستوری را که در فراخوانی خط فرمان پس از آن می‌آید اجرا کرده، سوکت کامپوزیتور Wayland مخصوص خود را راه‌اندازی می‌کند و تلاش می‌کند به سوکت متناظر waypipe client (به طور پیش‌فرض /tmp/waypipe-server.sock) متصل شود و تمامی کلاینت‌های Wayland را که به سوکت کامپوزیتور ساختگی متصل می‌شوند، به waypipe client متناظر هدایت نماید.

حالت waypipe bench می‌تواند برای برآورد اینکه کدام گزینه‌های فشرده‌سازی برای یک پهنای باند اتصال و تعداد نخ مشخص، کمترین تاخیر (latency) را ایجاد می‌کنند استفاده شود. این حالت دو تصویر ساختگی را آزمایش می‌کند؛ یکی به گونه‌ای ساخته شده که فشرده‌سازی آن تقریباً مشابه تصاویر حاوی متن باشد، و دیگری به گونه‌ای که فشرده‌سازی آن شبیه به تصاویر حاوی عکس و تصویر واقعی باشد.

-c C, --compress C

انتخاب روش فشرده‌سازی اعمال‌شده بر انتقال داده‌ها. گزینه‌ها عبارتند از none (برای شبکه‌های با پهنای باند بالا)، lz4 (متوسط) و zstd (اتصال کند). فشرده‌سازی پیش‌فرض lz4 است.† سطح فشرده‌سازی را می‌توان با افزودن = و در ادامه یک عدد تعیین کرد. برای مثال، اگر C برابر با zstd=7 باشد، waypipe از فشرده‌سازی Zstd با سطح ۷ استفاده خواهد کرد.

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

-d, --debug

چاپ پیام‌های گزارش اشکال‌زدایی (debug).

-h, --help

نمایش پیام راهنما و خروج.

-n, --no-gpu

مسدود کردن پروتکل‌هایی مانند wayland-drm و linux-dmabuf که نیازمند دسترسی به مواردی مانند گره‌های رندر (render nodes) هستند.

-o, --oneshot

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

-s S, --socket S

استفاده از S به عنوان مسیر سوکت Unix. مسیر پیش‌فرض سوکت برای حالت سرور /tmp/waypipe-server.sock است؛ برای حالت کلاینت /tmp/waypipe-client.sock است؛ و در حالت ssh، مقدار S پیشوند مورد استفاده توسط کلاینت و سرور را برای مسیرهای سوکتشان مشخص می‌کند. (مسیرهای واقعی سوکت در حالت ssh یک پسوند تصادفی به S اضافه می‌کنند.) پیشوند پیش‌فرض در حالت ssh مقدار /tmp/waypipe است.

هنگامی که vsock فعال است، از S برای تعیین یک CID و شماره پورت استفاده کنید.

--version

توضیح مختصر درباره نسخهٔ Waypipe و ویژگی‌هایی که با آن‌ها ساخته شده است، و سپس خروج. ویژگی‌های محتمل: پشتیبانی از فشرده‌سازی LZ4، پشتیبانی از فشرده‌سازی ZSTD، قابلیت انتقال DMABUFها، پشتیبانی از فشرده‌سازی ویدیو.

--display D

برای حالت سرور یا ssh، متغیر WAYLAND_DISPLAY را مشخص کرده و به waypipe اجازه می‌دهد تا سوکت نمایشگر Wayland خود را با مسیری متناظر پیکربندی کند. (اگر D یک مسیر مطلق نباشد، سوکت در پوشه‌ای ایجاد می‌شود که توسط متغیر محیطی XDG_RUNTIME_DIR مشخص شده است.)

--drm-node R

مشخص کردن مسیر R به دستگاه drm که این نمونه از waypipe باید استفاده کند و (در حالت سرور) برنامه‌های متصل‌شونده را از آن آگاه سازد.

--remote-node R

در حالت ssh، مسیر R به دستگاه drm را که نمونه دوردست waypipe (که در حالت سرور اجرا می‌شود) باید استفاده کند، مشخص می‌کند.

--ssh-bin R

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

--remote-bin R

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

--remote-socket R

در حالت ssh، پیشوند مورد استفاده توسط waypipe server دوردست را برای مسیر سوکت آن تعیین می‌کند. این مقدار تنها در سمت سرور بر گزینهٔ --socket تقدم دارد.

--login-shell

فقط برای حالت سرور؛ اگر دستوری در حال اجرا نباشد، یک پوسته ورود (login shell) باز می‌کند.

--threads T

تعیین تعداد کل نخ‌ها (شامل نخ اصلی) که یک نمونه از waypipe ایجاد خواهد کرد. این نخ‌ها برای موازی‌سازی عملیات فشرده‌سازی استفاده می‌شوند. این پرچم هنگام استفاده با waypipe ssh، به waypipe server نیز منتقل می‌شود. این پرچم همچنین تعداد نخ‌ها را برای waypipe bench کنترل می‌کند. رفتار پیش‌فرض (قابل انتخاب با قرار دادن T بر روی 0) استفاده از نصف نخ‌های سخت‌افزاری در دسترس رایانه است.

--title-prefix P

افزودن پیشوند P به عنوان تمامی پنجره‌هایی که با استفاده از پروتکل شل XDG مشخص شده‌اند. در حالت ssh، این پیشوند تنها در سمت کلاینت اعمال می‌شود.

--unlink-socket

فقط برای حالت سرور؛ هنگام خاتمه، سوکت Unix را که waypipe به آن متصل می‌شود حذف (unlink) می‌کند.

--video V

فشرده‌سازی قالب‌های مشخص DMABUF با استفاده از یک کدک ویدیویی اتلافی (lossy). قالب‌های مات (Opaque)، ۱۰ بیتی، و چندصفحه‌ای (multiplanar)، در کنار موارد دیگر، پشتیبانی نمی‌شوند. مقدار V فهرستی جدا شده با ویرگول از گزینه‌ها برای کنترل رمزگذاری ویدیو است. (برای مثال: --video av1,hw.) گزینه‌های بعدی بر گزینه‌های قبلی برتری دارند..PP none
عدم استفاده از کدگذاری ویدیو.

h264

استفاده از ویدیوی کدگذاری‌شده با H.264.

vp9

استفاده از ویدیوی کدگذاری‌شده با VP9.

av1

استفاده از ویدیوی کدگذاری‌شده با AV1.

sw, swenc, swdec

استفاده از کدگذاری یا رمزگشایی نرم‌افزاری، در صورت در دسترس بودن.

hw, hwenc, hwdec

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

bpf=B

تنظیم نرخ بیت (bit rate) هدف کدگذار ویدیو، بر حسب بیت بر فریم. B می‌تواند به صورت یک عدد صحیح یا با نماد نمایی نوشته شود؛ بنابراین --video=bpf=7.5e5 معادل --video=bpf=750000 است.

--vsock

استفاده از vsock به جای سوکت‌های unix. این گزینه هنگامی استفاده می‌شود که waypipe در ماشین‌های مجازی اجرا شود. با فعال بودن این گزینه، یک CID و یک شماره پورت را در S مشخص کنید. شناسه CID تنها در حالت سرور استفاده می‌شود و هنگام اتصال از یک ماشین مجازی مهمان به میزبان می‌توان آن را نادیده گرفت.

--secctx S

فعال‌سازی پروتکل زمینه امنیتی (security context) در ویلند (حالت‌های client یا ssh). یک شناسه برنامه S مشخص کنید که به زمینه امنیتی پیوست خواهد شد.

--xwls

استفاده از xwayland-satellite برای اجرای کلاینت‌های X در ویلند؛ برای حالت‌های server یا ssh. این گزینه سوکت‌های نمایشگر X را برای شماره نمایشگر آزاد بعدی متصل (bind) کرده و متغیر محیطی DISPLAY را برای برنامه‌ای که تحت waypipe server اجرا می‌شود، تنظیم می‌کند. این گزینه تنها در صورتی کار خواهد کرد که xwayland-satellite نصب بوده و در PATH موجود باشد.

--control C
--hwvideo
--allow-tiled

گزینه‌های موجود در نسخه‌های قدیمی‌تر Waypipe که حذف شده‌اند.

زیرفرمان waypipe ssh زیر تلاش می‌کند تا weston-flower را روی سرور exserv اجرا کند و نتیجه را روی سیستم محلی نمایش دهد.

waypipe ssh user@exserv weston-flower

می‌توان با اجرای صریح waypipe و ssh به رفتار مشابهی دست یافت:

waypipe --socket /tmp/socket-client client  &
ssh -R /tmp/socket-server:/tmp/socket-client user@exserv \
	waypipe --socket /tmp/socket-server server -- weston-flower
kill %1

Waypipe می‌تواند به صورت محلی و بدون اتصال SSH، از طریق تعیین مسیرهای سوکت مطابق با یکدیگر اجرا شود. برای مثال:

waypipe --socket /tmp/waypipe.sock client &
waypipe --socket /tmp/waypipe.sock server weston-simple-dmabuf-egl
kill %1
rm /tmp/waypipe.sock

استفاده از روش‌های انتقال غیر از SSH کمی پیچیده‌تر است. روشی با استفاده از ncat برای اتصال به remote از رایانه local:

$ waypipe --socket /tmp/waypipe-remote.sock client &
$ ncat --ssl -lk 12345 --sh-exec 'ncat -U /tmp/waypipe-remote.sock' &
$ ssh user@remote
> ncat -lkU /tmp/waypipe-local.sock --sh-exec 'ncat --ssl local 12345' &
> waypipe --display wayland-local \
            --socket /tmp/waypipe-local.sock server -- sleep inf &
> WAYLAND_DISPLAY=wayland-local application

با داشتن یک فایل گواهی (certificate)، ابزار socat نیز می‌تواند یک اتصال رمزگذاری‌شده فراهم کند (برای بررسی گواهی‌ها عبارت 'verify=0' را حذف کنید):

$ waypipe --socket /tmp/waypipe-remote.sock client &
$ socat openssl-listen:12345,reuseaddr,cert=certificate.pem,verify=0,fork \
    unix-connect:/tmp/waypipe-remote.sock
$ ssh user@remote
> socat unix-listen:/tmp/waypipe-local.sock,reuseaddr,fork \
    openssl-connect:local:12345,verify=0 &
> waypipe --socket /tmp/waypipe-local.sock server -- application

بسیاری از برنامه‌ها برای استفاده از ویلند به جای X11 نیازمند متغیرهای محیطی خاصی هستند. اگر ssh برای پشتیبانی از بارگذاری ~/.ssh/environment یا مجاز کردن تنظیم متغیرهای خاص با استفاده از AcceptEnv/SetEnv پیکربندی نشده باشد، می‌توان waypipe ssh را بدون دستور اجرا کرد (و در نتیجه یک پوسته ورود باز نمود)، یا از env برای تنظیم متغیرهای مورد نیاز در هر بار استفاده کرد:

waypipe ssh user@host env XDG_SESSION_TYPE=wayland dolphin

در برخی موارد، ممکن است بخواهید متغیرهای محیطی را برای خودِ فرایند waypipe server تنظیم کنید؛ ترفند بالا با دستور env این کار را انجام نمی‌دهد، زیرا فرایند env یک فرزند از waypipe server خواهد بود، نه برعکس. در عوض، می‌توان از ~/.ssh/environment استفاده کرد، یا با استفاده از گزینه --remote-bin نمونه Waypipe راه دور را به یک اسکریپت شل تغییر داد که محیط را قبل از اجرای برنامه اصلی waypipe تنظیم می‌کند.

هنگام اجرای waypipe در ماشین‌های مجازی روی یک میزبان (host) یکسان، امکان استفاده از vsock برای ارتباط بهینه بین ماشین‌های مجازی (inter-vm) وجود دارد. سناریوهای زیر پشتیبانی می‌شوند:

•
اجرای برنامه‌ها روی میزبان از طریق مهمان (guest).
host> waypipe --vsock -s 1234 client
guest> waypipe --vsock -s 1234 server weston-terminal
•
اجرای برنامه‌ها در یک ماشین مجازی مهمان از طریق میزبان.
guest> waypipe --vsock -s 1234 client
host> waypipe --vsock -s 3:1234 server weston-terminal

در این مثال، سرور waypipe به یک ماشین مجازی با CID 3 روی درگاه 1234 متصل می‌شود.

•
اجرای برنامه‌ها در یک ماشین مجازی مهمان از طریق ماشین‌های مجازی مهمان دیگر. هنگام اجرای هر دوی کلاینت و سرور در ماشین‌های مجازی، امکان فعال کردن پرچم VMADDR_FLAG_TO_HOST برای ارتباط با ماشین‌های همتا (sibling) با افزودن پیشوند s به CID وجود دارد:
guest> waypipe --vsock -s 1234 client
guest> waypipe --vsock -s s3:1234 server weston-terminal

در این حالت تمام بسته‌ها به میزبان هدایت خواهند شد، جایی که می‌توانند با استفاده از یک دستگاه vhost-device-vsock یا ابزاری دیگر به ماشین مجازی دیگری فوروارد شوند.

هنگام اجرا به عنوان سرور، به‌طور پیش‌فرض WAYLAND_DISPLAY برای فرایند فراخوانی‌شده تنظیم خواهد شد.

اگر پرچم --oneshot تعیین شده باشد، waypipe در عوض WAYLAND_SOCKET را تنظیم کرده و یک توصیف‌کننده فایل socketpair از پیش متصل‌شده را به فرایند فراخوانی‌شده (فرزند) به ارث می‌دهد. برخی برنامه‌ها در خلال مقداردهی اولیه خود مکرراً یک اتصال Wayland را باز و بسته می‌کنند و با این پرچم به‌درستی کار نخواهند کرد.

در صورت مواجهه با خطا، waypipe با کد وضعیت 1 خارج خواهد شد؛ در غیر این صورت، کد وضعیت خروج دستور در حال اجرا (یا 128 به‌علاوه مقدار سیگنال خاتمه‌دهنده) را، در صورت وجود، بازمی‌گرداند.

برنامه Waypipe هیچ‌گونه تضمین امنیتی قوی ارائه نمی‌دهد، و اتصال به سرورهای غیرقابل اعتماد توصیه نمی‌شود. این برنامه پروتکل‌های Wayland ارائه‌شده توسط کامپوزیتور به کلاینت را فیلتر نمی‌کند (به‌جز چند مورد استثنا برای پروتکل‌هایی که به توصیف‌کننده‌های فایل نیاز دارند و Waypipe هنوز نمی‌تواند آن‌ها را مدیریت کند). به عنوان مثال، اگر یک کامپوزیتور Wayland به تمام کلاینت‌های خود دسترسی به یک پروتکل اسکرین‌شات یا lock-screen را بدهد، کلاینت‌های پراکسی‌شده تحت Waypipe نیز می‌توانند اسکرین‌شات بگیرند یا صفحه را قفل کنند.

به‌طور کلی، برنامه‌ها در برابر کامپوزیتورهای مخرب به‌خوبی آزمایش نشده‌اند و کامپوزیتورها نیز در برابر کلاینت‌های مخرب آزموده نشده‌اند. برنامه Waypipe می‌تواند این دو را به یکدیگر متصل کند و ممکن است حملات منع سرویس (denial-of-service) و سایر حملات را بدون بررسی فوروارد کند.

خود Waypipe دارای کدهای ناامن (unsafe) فراوانی در زبان Rust است و به کتابخانه‌های فشرده‌سازی، گرافیک و ویدیو پیوند (link) می‌خورد؛ هم خود برنامه و هم این کتابخانه‌ها ممکن است دارای آسیب‌پذیری‌های امنیتی باشند. با ساختن (کامپایل) Waypipe با پشتیبانی غیرفعال از DMABUF، یا اجرای Waypipe با پرچم --no-gpu به نحوی که کتابخانه‌های گرافیکی را در دسترس قرار ندهد، می‌توان از بخشی از این خطرات اجتناب کرد.

دستور waypipe ssh هیچ حفاظت صریحی در برابر حملات زمان‌بندی (timing attacks) ندارد؛ یک ناظر بر ترافیک شبکه حاصل می‌تواند با بررسی اندازه و زمان‌بندی بسته‌ها، اطلاعاتی درباره تعامل کاربر با کلاینت Wayland پراکسی‌شده از طریق waypipe ssh به دست آورد. به عنوان مثال: عدم فعالیت نشان می‌دهد که کاربر در حال حاضر از برنامه استفاده نمی‌کند، در حالی که جریانی متناوب از پیام‌ها از کامپوزیتور به کلاینت ممکن است نشان‌دهنده حرکت ماوس باشد (یا شاید چیزی دیگر: محتوای پیام‌ها توسط ssh محافظت می‌شود.).

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

گزارش‌های باگ را در این نشانی ثبت کنید: https://gitlab.freedesktop.org/mstoeckl/waypipe

برخی از برنامه‌ها (از جمله gnome-terminal، firefox، kate) سازوکارهای ویژه‌ای دارند تا اطمینان حاصل شود که در هر زمان تنها یک فرایند در حال اجرا است. اجرای این برنامه‌ها تحت Waypipe در حالی که تحت یک کامپوزیتور Wayland دیگر در حال اجرا هستند، ممکن است بدون هیچ هشداری پنجره یا زبانه‌ای را در نمونه‌ی اصلی برنامه باز کند. چنین برنامه‌هایی ممکن است آرگومان خط فرمانی برای ایجاد یک نمونه‌ی جدید داشته باشند.

دستور waypipe ssh نیازمند آن است که فایل اجرایی ssh از فوروارد کردن سوکت Unix پشتیبانی کند؛ این قابلیت در OpenSSH تنها از نسخه 6.7 (از سال ۲۰۱۴) پشتیبانی می‌شود و ممکن است به پیکربندی خاصی نیاز داشته باشد. سایر پیاده‌سازی‌های SSH ممکن است قادر به فوروارد کردن سوکت‌های Unix نباشند؛ برای نحوه استفاده از روش‌های انتقال غیر SSH بخش مثال‌ها را در بالا ببینید.

weston(1)، ssh(1)، socat(1)، ncat(1)

2026-08-31