VARLINKCTL(1)

varlinkctl

VARLINKCTL(1)

نام (NAME)

varlinkctl - درون‌نگری و فراخوانی سرویس‌های Varlink

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

varlinkctl [OPTIONS...] info ADDRESS

varlinkctl [OPTIONS...] list-interfaces ADDRESS

varlinkctl [OPTIONS...] list-methods ADDRESS [INTERFACE...]

varlinkctl [OPTIONS...] introspect ADDRESS [INTERFACE...]

varlinkctl [OPTIONS...] call ADDRESS METHOD [ARGUMENTS]

varlinkctl [OPTIONS...] --exec call ADDRESS METHOD ARGUMENTS -- CMDLINE

varlinkctl [OPTIONS...] serve METHOD {CMDLINE...}

varlinkctl [OPTIONS...] validate-idl [FILE]

توضیحات (DESCRIPTION)

varlinkctl ممکن است برای درون‌نگری و فراخوانی سرویس‌های Varlink[1] استفاده شود.

سرویس‌ها با یکی از موارد زیر ارجاع داده می‌شوند:

•یک مرجع سرویس Varlink که با رشته‌ی "unix:" آغاز شده و به دنبال آن یک مسیر مطلق سوکت AF_UNIX، یا رشته‌ی "@" و یک رشته‌ی دلخواه قرار می‌گیرد (مورد دوم برای ارجاع به سوکت‌ها در فضای نام انتزاعی یا abstract namespace است). در این حالت، یک اتصال سوکت جریانی (stream socket) به سوکت مشخص‌شده برقرار می‌شود.

•یک مرجع سرویس Varlink که با رشته‌ی "exec:" آغاز شده و به دنبال آن مسیر مطلق یک فایل اجرایی (binary) قرار می‌گیرد. در این حالت، فرایند مشخص‌شده به صورت محلی انشعاب می‌یابد (fork می‌شود) و سوکت جریانی متصل‌شده به آن ارسال می‌گردد.

•یک مرجع سرویس Varlink که با رشته‌ی "ssh-unix:" آغاز شده و به دنبال آن مشخصات میزبان SSH، سپس ":"، و به دنبال آن یک مسیر مطلق سوکت AF_UNIX می‌آید. (این مورد به OpenSSH نسخه 9.4 یا جدیدتر در سمت سرور نیاز دارد و سوکت‌های فضای نام انتزاعی پشتیبانی نمی‌شوند.)

•یک مرجع سرویس Varlink که با رشته‌ی "ssh-exec:" آغاز شده و به دنبال آن مشخصات میزبان SSH، سپس ":"، و به دنبال آن یک خط فرمان می‌آید. در این حالت، دستور فراخوانی شده و پروتکل Varlink بر روی ورودی و خروجی استاندارد دستورِ فراخوانی‌شده گفتگو می‌شود.

برای سهولت، این دو نحو ساده‌تر (و مازاد) آدرس سرویس نیز پشتیبانی می‌شوند:

•یک مسیر فایل‌سیستمی به یک سوکت AF_UNIX، خواه مطلق (یعنی با "/" شروع شود) یا نسبی (که در این صورت باید با "./" شروع شود).

•یک مسیر فایل‌سیستمی به یک فایل اجرایی، خواه مطلق یا نسبی (همانند بالا، به ترتیب باید با "/" یا "./" شروع شود).

فرمان‌ها (COMMANDS)

فرمان‌های زیر پشتیبانی می‌شوند:

info ADDRESS

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

افزوده‌شده در نسخه 255.

list-interfaces ADDRESS

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

افزوده‌شده در نسخه 255.

list-methods ADDRESS [INTERFACE...]

فهرستی از متدهای پیاده‌سازی‌شده توسط سرویس مشخص‌شده را نمایش می‌دهد. آدرس سرویس در یکی از قالب‌های شرح‌داده‌شده در بالا و همچنین یک یا چند نام رابط را انتظار دارد. اگر نام رابطی مشخص نشود، تمام متدهای همه رابط‌های پیاده‌سازی‌شده توسط سرویس را فهرست می‌کند، در غیر این صورت فقط متدهای موجود در رابط‌های مشخص‌شده را فهرست می‌کند.

افزوده‌شده در نسخه 257.

introspect ADDRESS [INTERFACE...]

تعاریف رابط‌های مشخص‌شده را که توسط سرویس مشخص‌شده ارائه شده‌اند نمایش می‌دهد. آدرس سرویس در یکی از قالب‌های شرح‌داده‌شده در بالا و به صورت اختیاری یک یا چند نام رابط Varlink را انتظار دارد. اگر نام رابطی مشخص نشود، تمام رابط‌های ارائه‌شده توسط سرویس را نمایش می‌دهد.

افزوده‌شده در نسخه 255.

call ADDRESS METHOD [ARGUMENTS]

متد مشخص‌شده از سرویس مشخص‌شده را فراخوانی می‌کند. یک آدرس سرویس در قالب شرح‌داده‌شده در بالا، یک نام کامل متد Varlink، و یک شیء آرگومان‌های JSON را انتظار دارد. اگر شیء آرگومان‌ها مشخص نشود، به جای آن از STDIN خوانده می‌شود. برای ارسال یک فهرست خالی از پارامترها، شیء خالی "{}" را مشخص کنید.

پارامترهای پاسخ به عنوان اشیاء JSON در STDOUT نوشته می‌شوند.

افزوده‌شده در نسخه 255.

serve METHOD CMDLINE...

یک سرور Varlink را اجرا می‌کند که درخواست‌های ارتقای پروتکل را برای متد مشخص‌شده می‌پذیرد و اتصال ارتقایافته را به ورودی و خروجی استاندارد دستور مشخص‌شده متصل می‌کند. این دستور می‌تواند به عنوان یک همتای سمت سرور برای call --upgrade عمل کند.

سوکت شنود باید از طریق فعال‌سازی سوکت (یعنی پروتکل $LISTEN_FDS) منتقل شود، که این امر این دستور را برای استفاده در واحدهای سرویس فعال‌شونده با سوکت مناسب می‌سازد. هنگامی که یک کلاینت متد مشخص‌شده را با پرچم upgrade فراخوانی می‌کند، سرور پاسخی برای تأیید ارتقا ارسال کرده، سپس انشعاب یافته (fork می‌کند) و خط فرمان داده‌شده را با اتصال ارتقایافته بر روی ورودی و خروجی استاندارد خود اجرا می‌نماید.

این کار عملاً هر دستوری را که با پروتکلی از طریق ورودی/خروجی استاندارد گفتگو می‌کند، به یک سرویس Varlink تبدیل می‌سازد که از طریق رجیستری سرویس‌ها قابل کشف بوده و از طریق اعتبارسنجی سوکت احراز هویت می‌شود. از آنجا که هر اتصال توسط یک فرایند فرزند منشعب‌شده مدیریت می‌شود، واحد سرویس می‌تواند گزینه‌های محدودسازی محیطی (sandboxing) متعلق به systemd (مانند ProtectSystem= و غیره) را اعمال کند و در محیط فراخواننده کار نمی‌کند.

افزوده‌شده در نسخه 261.

list-registry

فهرستی از سرویس‌های Varlink را که در حال حاضر در رجیستری سرویس ثبت شده‌اند، به همراه سوکت‌های نقطه ورود آن‌ها نمایش می‌دهد. (در حال حاضر، این دستور صرفاً سوکت‌ها و سوکت‌های دارای پیوند نمادین را در /run/varlink/registry/ برمی‌شمرد، به زیر مراجعه کنید.)

افزوده‌شده در نسخه 260.

validate-idl [FILE]

یک فایل تعریف رابط Varlink را می‌خواند، آن را تجزیه و اعتبارسنجی می‌کند، سپس آن را با برجسته‌سازی نحوی خروجی می‌دهد. این کار نحو و سازگاری درونی رابط را بررسی می‌کند. نام فایلی را برای خواندن تعریف رابط از آن انتظار دارد. در صورت حذف، تعریف رابط را از STDIN می‌خواند.

افزوده‌شده در نسخه 255.

help

راهنمای نحو دستور را نمایش می‌دهد.

افزوده‌شده در نسخه 255.

گزینه‌ها (OPTIONS)

گزینه‌های زیر پشتیبانی می‌شوند:

--more

هنگام استفاده با call: انتظار چندین پاسخ متد را داشته باشد. اگر این پرچم تنظیم شود، فراخوانی متد با پرچم تنظیم‌شده‌ی more ارسال می‌شود که به سرویس اعلام می‌کند در صورت نیاز، چندین پاسخ تولید کند. دستور تا زمانی که سرویس پیام پاسخی مبنی بر اینکه این آخرین پیام در مجموعه است ارسال کند (یا در صورتی که مهلت زمانی پیکربندی‌شده سپری شود، زیر را ببینید) در حال اجرا باقی می‌ماند. این پرچم فقط باید برای فراخوانی‌های متدی که از این سازوکار پشتیبانی می‌کنند تنظیم شود.

اگر این حالت فعال باشد، خروجی به صورت خودکار به حالت JSON-SEQ تغییر می‌یابد تا اشیاء پاسخ جداگانه به سادگی قابل تشخیص باشند.

این سوئیچ هیچ اثری بر مهلت زمانی فراخوانی متد که به طور پیش‌فرض اعمال می‌شود ندارد. صرف‌نظر از اینکه --more مشخص شده باشد یا خیر، مهلت زمانی پیش‌فرض ۴۵ ثانیه خواهد بود. از --timeout= (زیر را ببینید) برای تغییر یا غیرفعال کردن مهلت زمانی استفاده کنید. هنگام اجرای یک فراخوانی متد که پیوسته به‌روزرسانی‌ها را برمی‌گرداند، معمولاً مطلوب است که مهلت زمانی با --timeout=infinity غیرفعال شود. از سوی دیگر، هنگام اجرای فراخوانی متد با --more به منظور شمارش اشیاء (که احتمالاً سریعاً تکمیل می‌شود)، معمولاً به دلایل پایداری و استحکام، سودمند است که منطق مهلت زمانی فعال بماند.

افزوده‌شده در نسخه 255.

-E

میانبری برای --more --timeout=infinity. این سوئیچ برای فراخوانی‌های متدی که اشتراک در یک جریان پیوسته از به‌روزرسانی‌ها را پیاده‌سازی می‌کنند، مفید است.

افزوده‌شده در نسخه 257.

--collect

این گزینه شبیه به --more است، اما به جای حالت JSON-SEQ، تمام پاسخ‌ها را در یک آرایه JSON جمع‌آوری کرده و چاپ می‌کند.

افزوده‌شده در نسخه 256.

--oneway

هنگام استفاده با call: منتظر پاسخ متد نباشد. اگر این پرچم تنظیم شود، فراخوانی متد با پرچم تنظیم‌شده‌ی oneway ارسال می‌شود (دستور بلافاصله پس از آن خارج می‌شود) که به سرویس اعلام می‌کند پاسخی تولید نکند.

افزوده‌شده در نسخه 255.

--upgrade

هنگام استفاده با call: درخواست ارتقای پروتکل بدهد. فراخوانی متد با پرچم تنظیم‌شده‌ی upgrade ارسال می‌شود. انتظار می‌رود سرویس یک پاسخ واحد برای تأیید ارتقا ارسال کند. پس از پاسخ، پروتکل Varlink دیگر بر روی اتصال اعمال نخواهد شد.

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

اگر --exec مشخص شده باشد، سوکت اتصال ارتقایافته بر روی هر دوی ورودی استاندارد و خروجی استانداردِ فرایندِ فراخوانی‌شده قرار می‌گیرد. این شبیه به رفتار معمول --exec (بدون --upgrade) است که پاسخ فراخوانی متد را بر روی ورودی استاندارد قرار می‌دهد. بنابراین فرایند فراخوانی‌شده می‌تواند به سادگی از stdin/stdout برای برقراری ارتباط بر بستر پروتکل ارتقایافته بخواند و در آن بنویسد.

این گزینه ممکن است با --more، --oneway، --collect، --graceful=، یا --push-fd= ترکیب نشود.

افزوده‌شده در نسخه 261.

--json=MODE

قالب‌بندی خروجی JSON را انتخاب می‌کند؛ یا "pretty" برای خروجی دارای تورفتگی مناسب و رنگی، یا "short" برای خروجی فشرده با حداقل فاصله سفید و بدون خطوط جدید. پیش‌فرض "short" است.

افزوده‌شده در نسخه 255.

-j

معادل --json=pretty هنگام فراخوانی به صورت تعاملی از یک ترمینال. در غیر این صورت معادل --json=short است، به ویژه زمانی که خروجی به برنامه دیگری هدایت (pipe) می‌شود.

افزوده‌شده در نسخه 255.

--quiet, -q

سرکوب خروجی پاسخ‌های فراخوانی متد.

افزوده‌شده در نسخه 257.

--graceful=

یک نام خطای کامل (واجد شرایط) Varlink، یعنی یک نام رابط به همراه پسوند نام خطا که با نقطه جدا شده‌اند را می‌پذیرد، مانند "org.varlink.service.InvalidParameter". اطمینان حاصل می‌کند که اگر فراخوانی متد با خطای مشخص‌شده ناموفق شود، این حالت به عنوان موفقیت تلقی گردد؛ یعنی باعث می‌شود فراخوانی varlinkctl با کد خروج صفر به پایان برسد. این گزینه ممکن است بیش از یک بار استفاده شود تا چندین خطای مختلف به عنوان موفقیت در نظر گرفته شوند.

افزوده‌شده در نسخه 257.

--timeout=

یک مهلت زمانی بر حسب ثانیه را به عنوان پارامتر انتظار دارد. به طور پیش‌فرض، یک مهلت زمانی ۴۵ ثانیه‌ای اعمال می‌شود. برای خاموش کردن مهلت زمانی، "infinity" یا یک رشته خالی را مشخص کنید.

افزوده‌شده در نسخه 257.

--exec

پس از اینکه فراخوانی متد صادرشده از طریق call با موفقیت تکمیل شد، خط فرمان مشخص‌شده را اجرا و زنجیره‌ای (chainload) می‌کند، در حالی که پارامترهای خروجی فراخوانی متد به صورت سریال‌شده به JSON به ورودی استاندارد فرستاده می‌شوند (و خروجی استاندارد و خطای استاندارد از فرایند فراخواننده به ارث برده می‌شوند). علاوه بر این، هر توصیف‌کننده فایل که از سوکت ارتباطی زیرین برگشت داده شود، از طریق پروتکل معمول $LISTEN_FDS به فرایند فراخوانی‌شده ارسال می‌گردد. این قابلیت می‌تواند برای پردازش و دریافت پاسخ‌هایی که همراه با توصیف‌کننده‌های فایل مرتبط هستند به روشی مناسب استفاده شود.

توجه داشته باشید که اگر --exec مشخص شود، پارامتر سوم call (یعنی پارامترهای فراخوانی متد) اختیاری نخواهد بود.

افزوده‌شده در نسخه 258.

--push-fd=

یک عدد توصیف‌کننده فایل عددی را به عنوان پارامتر می‌پذیرد. در صورتی که بستر انتقال زیرین از این کار پشتیبانی کند، ممکن است برای ارسال یک توصیف‌کننده فایل به همراه فراخوانی متد استفاده شود. ممکن است چندین بار برای ارسال چندین توصیف‌کننده فایل استفاده شود، با حفظ ترتیبی که در آن مشخص شده‌اند. توصیف‌کننده‌های فایل مشخص‌شده باید به فراخوانی varlinkctl منتقل شوند. به صورت اختیاری، به جای یک شماره توصیف‌کننده فایل عددی، می‌توان یک مسیر فایل‌سیستمی مطلق یا نسبی (که در حالت دوم باید پیشوند "./" داشته باشد) را مشخص کرد که در حالت فقط‌خواندنی باز می‌شود.

افزوده‌شده در نسخه 258.

--system, --user

تعیین می‌کند که هنگام استفاده از دستور list-registry پرس‌وجو از رجیستری سیستم انجام شود یا رجیستری کاربر. به طور پیش‌فرض، از رجیستری سیستم پرس‌وجو می‌شود.

افزوده‌شده در نسخه 260.

--no-ask-password

برای عملیات‌های نیازمند امتیاز، از کاربر درخواست احراز هویت نکند.

--no-pager

خروجی را به یک صفحه‌بند (pager) هدایت نکند.

-h, --help

یک متن راهنمای کوتاه را چاپ کرده و خارج شود.

--version

یک رشته نسخه کوتاه را چاپ کرده و خارج شود.

فایل‌ها و دایرکتوری‌ها (FILES & DIRECTORIES)

/run/varlink/registry/

دایرکتوری حاوی اینودهای سوکت نقطه ورود AF_UNIX (یا پیوندهای نمادین به آن‌ها) مربوط به رابط‌های شناخته‌شده و عمومی Varlink در سیستم محلی. نام آن‌ها بر اساس رابط Varlink که پیاده‌سازی می‌کنند تعیین می‌شود.

از varlinkctl list-registry برای نمایش محتویات این دایرکتوری استفاده کنید.

(اینودهایی که نه به عنوان اینودهای سوکت و نه به عنوان پیوندهای نمادین به آن‌ها واجد شرایط نباشند، باید نادیده گرفته شوند. یک توسعه در آینده ممکن است فایل‌ها و دایرکتوری‌های معمولی را برای بهبود قابلیت‌های رجیستری معرفی کند.)

افزوده‌شده در نسخه 260.

مثال‌ها (EXAMPLES)

مثال ۱. بررسی یک سرویس

سه دستور زیر سرویس "io.systemd.Resolve" پیاده‌سازی‌شده توسط systemd-resolved.service(8) را بازرسی می‌کنند، اطلاعات عمومی سرویس و رابط‌های پیاده‌سازی‌شده را فهرست می‌کنند و سپس تعریف رابط اصلی آن را نمایش می‌دهند:

$ varlinkctl info /run/systemd/resolve/io.systemd.Resolve
    Vendor: The systemd Project
   Product: systemd (systemd-resolved)
   Version: 254 (254-1522-g4790521^)
       URL: https://systemd.io
Interfaces: io.systemd
            io.systemd.Resolve
            org.varlink.service
$ varlinkctl list-interfaces /run/systemd/resolve/io.systemd.Resolve
io.systemd
io.systemd.Resolve
org.varlink.service
$ varlinkctl introspect /run/systemd/resolve/io.systemd.Resolve io.systemd.Resolve
interface io.systemd.Resolve
type ResolvedAddress(
        ifindex: ?int,
        ...

(تعریف رابط در مثال بالا برای رعایت اختصار کوتاه شده است.)

مثال ۲. فراخوانی یک متد

دستور زیر یک نام میزبان را از طریق فراخوانی متد ResolveHostname از systemd-resolved.service(8) تحلیل می‌کند.

$ varlinkctl call /run/systemd/resolve/io.systemd.Resolve io.systemd.Resolve.ResolveHostname '{"name":"systemd.io","family":2}' -j
{
        "addresses" : [
                {
                        "ifindex" : 2,
                        "family" : 2,
                        "address" : [
                                185,
                                199,
                                111,
                                153
                        ]
                }
        ],
        "name" : "systemd.io",
        "flags" : 1048577
}

مثال ۳. بررسی یک فایل اجرایی سرویس

دستور زیر فایل اجرایی /usr/lib/systemd/systemd-pcrextend و رابط‌های IPC ارائه‌شده توسط آن را بازرسی می‌کند. سپس متدی را بر روی آن فراخوانی می‌کند:

# varlinkctl info /usr/lib/systemd/systemd-pcrextend
    Vendor: The systemd Project
   Product: systemd (systemd-pcrextend)
   Version: 254 (254-1536-g97734fb)
       URL: https://systemd.io
Interfaces: io.systemd
            io.systemd.PCRExtend
            org.varlink.service
# varlinkctl introspect /usr/lib/systemd/systemd-pcrextend io.systemd.PCRExtend
interface io.systemd.PCRExtend
method Extend(
        pcr: int,
        text: ?string,
        data: ?string
) -> ()
# varlinkctl call /usr/lib/systemd/systemd-pcrextend io.systemd.PCRExtend.Extend '{"pcr":15,"text":"foobar"}'
{}

مثال ۴. فراخوانی یک متد از راه دور از طریق SSH

دستور زیر گزارشی درباره هویت یک میزبان راه دور به نام "somehost" را از systemd-hostnamed.service(8) با اتصال از طریق SSH به سوکت AF_UNIX که سرویس روی آن شنود می‌کند، دریافت می‌نماید:

# varlinkctl call ssh-unix:somehost:/run/systemd/io.systemd.Hostname io.systemd.Hostname.Describe '{}'

برای فراخوانی مستقیم یک فایل باینری سرویس Varlink بر روی میزبان از راه دور، به جای ارتباط با سرویس از طریق AF_UNIX، می‌توان این کار را به شکل زیر انجام داد:

# varlinkctl call ssh-exec:somehost:systemd-creds org.varlink.service.GetInfo '{}'

مثال ۵. ارائه یک فشرده‌گشای ایزوله‌شده از طریق ارتقای پروتکل

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

# /etc/systemd/system/varlink-decompress-xz.socket
[Socket]
ListenStream=/run/varlink/registry/com.example.Decompress.XZ
[Install]
WantedBy=sockets.target
# /etc/systemd/system/varlink-decompress-xz.service
[Service]
ExecStart=varlinkctl serve com.example.Decompress.XZ xz -d
DynamicUser=yes
PrivateNetwork=yes
ProtectSystem=strict
ProtectHome=yes
NoNewPrivileges=yes
SystemCallFilter=~@privileged @resources
MemoryMax=256M

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

$ echo "hello" | xz | varlinkctl call --upgrade \
        unix:/run/varlink/registry/com.example.Decompress.XZ \
        com.example.Decompress.XZ '{}'
hello

برای آزمایش سریع بدون نیاز به فایل‌های واحد، systemd-socket-activate می‌تواند برای ارائه سوکت شنود استفاده شود:

$ systemd-socket-activate -l /tmp/decompress.sock -- varlinkctl serve com.example.Decompress.XZ xz -d &
$ echo "hello" | xz | varlinkctl call --upgrade unix:/tmp/decompress.sock com.example.Decompress.XZ '{}'
hello

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

busctl(1), Varlink[1]

نکات (NOTES)

1.: Varlink

https://varlink.org

systemd 261.2