VARLINKCTL(1)

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

موجز

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

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

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

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

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

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

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.

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.

--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 '{}'

انظر أيضًا

busctl(1), Varlink[1]

ملاحظات

1.  Varlink
    https://varlink.org/

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

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

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