Scroll to navigation

VARLINKCTL(1) varlinkctl VARLINKCTL(1)

الاسم

varlinkctl - استكشف واستدعِ خدمات Varlink

موجز

varlinkctl [خيارات...] معلومات العنوان

varlinkctl [خيارات...] قائمة-الواجهات العنوان

varlinkctl [خيارات...] قائمة-الطرق العنوان [الواجهة...]

varlinkctl [خيارات...] استكشف العنوان [الواجهة...]

varlinkctl [خيارات...] استدعِ العنوان الطريقة [الوسائط]

varlinkctl [خيارات...] --exec call عنوان طريقة معطيات -- CMDLINE

varlinkctl [خيارات...] serve دالة {سطر_أوامر...}

varlinkctl [خيارات...] تحقق-من-idl [الملف]

الوصف

يمكن استخدام varlinkctl لاستكشاف واستدعاء خدمات Varlink[1].

يتم الإشارة إلى الخدمات بواحد مما يلي:

•مرجع خدمة Varlink يبدأ بالسلسلة "unix:"، متبوعًا بمسار مأخذ AF_UNIX مطلق، أو بـ "@" وسلسلة عشوائية (الأخير للإشارة إلى مآخذ في النطاق المجرد). في هذه الحالة، يتم إنشاء اتصال مأخذ تدفق بالمأخذ المحدد.

•مرجع خدمة Varlink يبدأ بالسلسلة "exec:"، متبوعًا بمسار مطلق لملف ثنائي للتنفيذ. في هذه الحالة، يتم تفريع العملية المحددة محليًا، مع تمرير مأخذ تدفق متصل.

•مرجع خدمة Varlink يبدأ بالسلسلة "ssh-unix:"، متبوعًا بمواصفات مضيف SSH، ثم ":"، ثم مسار مأخذ AF_UNIX مطلق. (يتطلب هذا OpenSSH 9.4 أو أحدث على جانب الخادم، ولا تدعم مآخذ النطاق المجرد.)

•مرجع خدمة Varlink يبدأ بالسلسلة "ssh-exec:"، متبوعًا بمواصفات مضيف SSH، ثم ":"، ثم سطر أوامر. في هذه الحالة، يتم استدعاء الأمر ويتم التحدث ببروتوكول Varlink على الإدخال والإخراج القياسيين للأمر المستدعى.

للتسهيل، يتم دعم هاتين الصيغتين الأبسط (المكررة) لعنوان الخدمة أيضًا:

•مسار نظام ملفات إلى مأخذ AF_UNIX، إما مطلق (أي يبدأ بـ "/") أو نسبي (وفي هذه الحالة يجب أن يبدأ بـ "./").

•مسار نظام ملفات إلى ملف قابل للتنفيذ، إما مطلق أو نسبي (كما سبق، يجب أن يبدأ بـ "/" أو "./" على التوالي).

الأوامر

الأوامر التالية مفهومة:

info العنوان

يعرض معلومات موجزة عن الخدمة المحددة، بما في ذلك اسم البائع وقائمة الواجهات المنفذة. يتوقع عنوان خدمة بأحد التنسيقات الموصوفة أعلاه.

أُضيف في الإصدار 255.

list-interfaces العنوان

يعرض قائمة بالواجهات المنفذة بواسطة الخدمة المحددة. يتوقع عنوان خدمة بأحد التنسيقات الموصوفة أعلاه.

أُضيف في الإصدار 255.

list-methods ADDRESS [INTERFACE...]

يعرض قائمة بالطرق المنفذة بواسطة الخدمة المحددة. يتوقع عنوان خدمة بأحد التنسيقات الموصوفة أعلاه بالإضافة إلى اسم واجهة واحد أو أكثر. إذا لم يتم تحديد اسم واجهة، يسرد جميع طرق جميع الواجهات المنفذة بواسطة الخدمة، وإلا فقط الطرق في الواجهات المحددة.

أُضيف في الإصدار 257.

introspect ADDRESS [INTERFACE...]

يعرض تعريفات الواجهة للواجهات المحددة المقدمة بواسطة الخدمة المحددة. يتوقع عنوان خدمة بأحد التنسيقات الموصوفة أعلاه واختياريًا اسم واجهة Varlink واحد أو أكثر. إذا لم يتم تحديد أسماء واجهات، يعرض جميع الواجهات المقدمة بواسطة الخدمة.

أُضيف في الإصدار 255.

call ADDRESS METHOD [ARGUMENTS]

يستدعي الطريقة المحددة للخدمة المحددة. يتوقع عنوان خدمة بالتنسيق الموصوف أعلاه، واسم طريقة Varlink مؤهل بالكامل، وكائن وسائط JSON. إذا لم يتم تحديد كائن الوسائط، يتم قراءته من STDIN بدلاً من ذلك. لتمرير قائمة فارغة من المعاملات، حدد الكائن الفارغ "{}".

تتم كتابة معاملات الرد ككائنات JSON إلى STDOUT.

أُضيف في الإصدار 255.

serve طريقة سطر_أوامر...

شغّل خادم Varlink يقبل طلبات ترقية البروتوكول للطريقة المحددة ويصل الاتصال المُرقّى بالإدخال والإخراج القياسيين للأمر المحدد. يمكن أن يعمل هذا كطرف خادم مقابل لـ call --upgrade.

يجب تمرير مقبس الاستماع عبر تفعيل المقبس (أي بروتوكول $LISTEN_FDS)، مما يجعل هذا الأمر مناسبًا للاستخدام في وحدات الخدمة المُفعّلة بالمقبس. عندما يستدعي عميل الطريقة المحددة مع علامة الترقية، يرسل الخادم ردًا يؤكد الترقية، ثم يتفرع وينفذ سطر الأمر المُعطى مع الاتصال المُرقّى على إدخاله وإخراجه القياسيين.

يحول هذا فعليًا أي أمر يتحدث بروتوكولًا عبر الإدخال/الإخراج القياسيين إلى خدمة Varlink، يمكن اكتشافها عبر سجل الخدمة والمصادقة عليها عبر بيانات اعتماد المقبس. نظرًا لأن كل اتصال يُعالج بواسطة عملية فرعية متفرعة، يمكن لوحدة الخدمة تطبيق خيارات العزل الخاصة بـ systemd (مثل ProtectSystem=، إلخ.) ولا تعمل في بيئة المستدعي.

أُضيف في الإصدار 261.

list-registry

يعرض قائمة بخدمات Varlink المسجلة حالياً في سجل الخدمة، بالإضافة إلى مقابس نقاط الدخول الخاصة بها. (حالياً، يقوم هذا ببساطة بتعداد المقابس والمقابس المرتبطة رمزياً في /run/varlink/registry/، انظر أدناه.)

أُضيف في الإصدار 260.

validate-idl [FILE]

يقرأ ملف تعريف واجهة Varlink، ويحلله ويتحقق من صحته، ثم يخرجه مع إبراز بناء الجملة. يتحقق هذا من بناء الجملة والاتساق الداخلي للواجهة. يتوقع اسم ملف لقراءة تعريف الواجهة منه. إذا تم حذفه، يقرأ تعريف الواجهة من STDIN.

أُضيف في الإصدار 255.

help

يعرض مساعدة بناء جملة الأمر.

أُضيف في الإصدار 255.

الخيارات

الخيارات التالية مفهومة:

--more

عند استخدامه مع call: توقع ردود طريقة متعددة. إذا تم تعيين هذه العلامة، يتم إرسال استدعاء الطريقة مع تعيين علامة more، والتي تخبر الخدمة بتوليد ردود متعددة، إذا لزم الأمر. يظل الأمر قيد التشغيل حتى ترسل الخدمة رسالة رد تشير إلى أنها الأخيرة في السلسلة (أو إذا تم الوصول إلى المهلة المكونة، انظر أدناه). يجب تعيين هذه العلامة فقط لاستدعاءات الطريقة التي تدعم هذه الآلية.

إذا تم تمكين هذا الوضع، يتم تحويل الإخراج آلياً إلى وضع JSON-SEQ، بحيث يمكن تمييز كائنات الرد الفردية بسهولة.

ليس لهذا المفتاح أي تأثير على مهلة استدعاء الطريقة المطبقة مبدئياً. بغض النظر عما إذا تم تحديد --more أم لا، ستكون المهلة المبدئية 45 ثانية. استخدم --timeout= (انظر أدناه) لتغيير أو تعطيل المهلة. عند استدعاء استدعاء طريقة يعيد التحديثات باستمرار، من المرغوب عادةً تعطيل المهلة باستخدام --timeout=infinity. من ناحية أخرى، عند استدعاء استدعاء طريقة --more لغرض تعداد الكائنات (والذي من المحتمل أن يكتمل بسرعة)، من المفيد عادةً ترك منطق المهلة ممكناً، لأسباب تتعلق بالمتانة.

أُضيف في الإصدار 255.

-E

اختصار لـ --more --timeout=infinity. هذا المفتاح مفيد لاستدعاءات الطريقة التي تنفذ الاشتراك في تدفق مستمر من التحديثات.

أُضيف في الإصدار 257.

--collect

هذا مشابه لـ --more، لكنه يجمع كل الردود في مصفوفة JSON، ويطبعها، بدلاً من وضع JSON-SEQ.

أُضيف في الإصدار 256.

--oneway

عند استخدامه مع call: لا تتوقع رد طريقة. إذا تم تعيين هذه العلامة، يتم إرسال استدعاء الطريقة مع تعيين علامة oneway (يخرج الأمر فوراً بعد ذلك)، والتي تخبر الخدمة بعدم توليد رد.

أُضيف في الإصدار 255.

--upgrade

عند استخدامه مع call: اطلب ترقية البروتوكول. يُرسل استدعاء الطريقة مع تعيين علامة upgrade. يُتوقع من الخدمة إرسال رد واحد يؤكد الترقية. بعد الرد، لم يعد بروتوكول Varlink ساري المفعول على الاتصال.

إذا لم يُحدد --exec، يعمل varlinkctl كوسيط ثنائي الاتجاه: تُمرر البيانات المقروءة من الإدخال القياسي إلى الاتصال المُرقّى، وتُكتب البيانات المستلمة من الاتصال إلى الإخراج القياسي.

إذا حُدد --exec، يُوضع مقبس الاتصال المُرقّى على كل من الإدخال القياسي والإخراج القياسي للعملية المستدعاة. هذا مشابه لسلوك --exec العادي (بدون --upgrade)، الذي يضع رد استدعاء الطريقة على الإدخال القياسي. يمكن للعملية المستدعاة ببساطة القراءة من stdin والكتابة إلى stdout للتواصل عبر البروتوكول المُرقّى.

لا يجوز دمج هذا الخيار مع --more أو --oneway أو --collect أو --graceful= أو --push-fd=.

أُضيف في الإصدار 261.

--json=وضع

يختار تنسيق إخراج JSON، إما "pretty" لإخراج ملون وذو مسافة بادئة جيدة، أو "short" لإخراج موجز مع حد أدنى من المسافات البيضاء وبدون أسطر جديدة. المبدئي هو "short".

أُضيف في الإصدار 255.

-j

مكافئ لـ --json=pretty عند استدعائه تفاعلياً من طرفية. بخلاف ذلك، فهو مكافئ لـ --json=short، خاصة عندما يتم توجيه الإخراج إلى برنامج آخر.

أُضيف في الإصدار 255.

--quiet،‏ -q

قم بكتم إخراج ردود استدعاء الطريقة.

أُضيف في الإصدار 257.

--graceful=

يأخذ اسم خطأ Varlink مؤهلاً، أي اسم واجهة، متبوعاً باسم خطأ، مفصولاً بنقطة، على سبيل المثال "org.varlink.service.InvalidParameter". يضمن أنه إذا فشل استدعاء طريقة بالخطأ المحدد، فسيتم التعامل معه كنجاح، أي سيتسبب في خروج استدعاء varlinkctl بحالة خروج صفرية. يمكن استخدام هذا الخيار أكثر من مرة لمعالجة أخطاء متعددة مختلفة كنجاحات.

أُضيف في الإصدار 257.

--timeout=

يتوقع مهلة بالثواني كمعامل. مبدئياً، يتم فرض مهلة 45 ثانية. لإيقاف تشغيل المهلة، حدد "infinity" أو سلسلة فارغة.

أُضيف في الإصدار 257.

--exec

بمجرد اكتمال استدعاء الطريقة الصادر عبر call بنجاح، قم بتحميل سلسلة الأوامر المحددة، مع معاملات إخراج استدعاء الطريقة المسلسلة إلى JSON التي تم تمريرها إلى الإدخال القياسي (والإخراج القياسي والخطأ القياسي الموروث من العملية المستدعية). علاوة على ذلك، يتم تمرير أي واصفات ملفات يتم إرجاعها على مقبس الاتصال الأساسي إلى العملية المستدعاة عبر بروتوكول $LISTEN_FDS المعتاد. يمكن استخدام هذه الوظيفة لاستهلاك الردود التي تأتي مع واصفات ملفات مرتبطة بطريقة معقولة.

الآن إذا تم تحديد --exec، فإن المعامل الثالث لـ call ليس اختيارياً (أي معاملات استدعاء الطريقة).

أُضيف في الإصدار 258.

--push-fd=

يأخذ رقمًا رقميًا لمؤشر الملف كمعلمة. يمكن استخدامه لتمرير مؤشر ملف مع استدعاء الأسلوب، إذا كان نظام النقل الأساسي يدعم ذلك. يمكن استخدامه عدة مرات لتمرير مؤشرات ملفات متعددة، مع الحفاظ على الترتيب المُحدد لها. يجب تمرير مؤشرات الملفات المحددة إلى استدعاء varlinkctl. اختياريًا، بدلاً من رقم واصف الملف الرقمي، يمكن تحديد مسار نظام ملفات مطلق أو نسبي (يجب أن يسبق الأخير بـ ”./“)، ويُفتح في وضع القراءة فقط.

أُضيف في الإصدار 258.

--system، --user

يحدد ما إذا كان سيتم الاستعلام إلى السجل لكل نظام أو لكل مستخدم عند استخدام أمر list-registry. مبدئياً، يتم الاستعلام عن السجل لكل نظام.

أُضيف في الإصدار 260.

--no-ask-password

لا تسأل المستخدم عن الاستيثاق للعمليات ذات الامتيازات.

--no-pager

لا تمرر المخرجات إلى برنامج عرض (pager).

-h، --help

اطبع نص مساعدة قصير واخرج.

--version

اطبع سلسلة إصدار قصيرة واخرج.

الملفات والأدلة

/run/varlink/registry/

دليل يحتوي على عقد مقبس نقطة دخول AF_UNIX (أو روابط رمزية لها) لواجهات Varlink العامة المعروفة على النظام المحلي. يتم تسميتها على اسم واجهة Varlink التي تنفذها.

استخدم varlinkctl list-registry لعرض محتويات هذا الدليل.

(سيتم تجاهل العقد التي لا تعتبر عقد مقبس ولا روابط رمزية لها. قد يقدم امتداد مستقبلي ملفات وأدلة عادية لتعزيز وظيفة السجل.)

أُضيف في الإصدار 260.

أمثلة

مثال 1. التحقيق في خدمة

تفحص الأوامر الثلاثة التالية خدمة "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,


        ...

(تم اقتطاع تعريف الواجهة في المثال أعلاه، من أجل الإيجاز.)

مثال 2. استدعاء طريقة

الأمر التالي يحل اسم مضيف عبر استدعاء الأسلوب 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
}

مثال 3. التحقيق في ملف تنفيذي لخدمة

الأمر التالي يفحص الملف التنفيذي /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"}'
{}

مثال 4. استدعاء أسلوب عن بُعد عبر 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 '{}'

مثال 5. تقديم أداة فك ضغط معزولة عبر ترقية البروتوكول

تعرض وحدات المقبس والخدمة التالية فك ضغط 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

انظر أيضًا

busctl(1), Varlink[1]

ملاحظات

1.
Varlink
https://varlink.org/

ترجمة

تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي <zayed.alsaidi@gmail.com>

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: kde-l10n-ar@kde.org.

systemd 261~rc3