table of contents
| ORG.FREEDESKTOP.IMPORT1(5) | org.freedesktop.import1 | ORG.FREEDESKTOP.IMPORT1(5) |
الاسم¶
org.freedesktop.import1 - واجهة D-Bus لـ systemd-importd
مقدمة¶
systemd-importd.service(8) هي خدمة نظام يمكن استخدامها لاستيراد وتصدير وتنزيل صور الأقراص. يمكن استخدام هذه الصور بواسطة أدوات مثل systemd-nspawn(1) لتشغيل الحاويات المحلية. تُستخدم الخدمة كخلفية لـ importctl pull-raw و importctl pull-tar والأوامر ذات الصلة. تصف هذه الصفحة واجهة D-Bus.
لاحظ أن systemd-importd.service(8) هي في الغالب خدمة مصاحبة صغيرة لـ systemd-machined.service(8). العديد من العمليات لمعالجة صور الحاويات المحلية والأجهزة الافتراضية متاحة بالتالي عبر واجهة برمجة تطبيقات D-Bus لـ systemd-machined، راجع org.freedesktop.machine1(5).
كائن المدير¶
تعرض الخدمة الواجهات التالية على كائن المدير (Manager) على الناقل (bus):
node /org/freedesktop/import1 {
interface org.freedesktop.import1.Manager {
methods:
ImportTar(in h fd,
in s local_name,
in b force,
in b read_only,
out u transfer_id,
out o transfer_path);
ImportTarEx(in h fd,
in s local_name,
in s class,
in t flags,
out u transfer_id,
out o transfer_path);
ImportRaw(in h fd,
in s local_name,
in b force,
in b read_only,
out u transfer_id,
out o transfer_path);
ImportRawEx(in h fd,
in s local_name,
in s class,
in t flags,
out u transfer_id,
out o transfer_path);
ImportFileSystem(in h fd,
in s local_name,
in b force,
in b read_only,
out u transfer_id,
out o transfer_path);
ImportFileSystemEx(in h fd,
in s local_name,
in s class,
in t flags,
out u transfer_id,
out o transfer_path);
ExportTar(in s local_name,
in h fd,
in s format,
out u transfer_id,
out o transfer_path);
ExportTarEx(in s local_name,
in s class,
in h fd,
in s format,
in t flags,
out u transfer_id,
out o transfer_path);
ExportRaw(in s local_name,
in h fd,
in s format,
out u transfer_id,
out o transfer_path);
ExportRawEx(in s local_name,
in s class,
in h fd,
in s format,
in t flags,
out u transfer_id,
out o transfer_path);
PullTar(in s url,
in s local_name,
in s verify_mode,
in b force,
out u transfer_id,
out o transfer_path);
PullTarEx(in s url,
in s local_name,
in s class,
in s verify_mode,
in t flags,
out u transfer_id,
out o transfer_path);
PullRaw(in s url,
in s local_name,
in s verify_mode,
in b force,
out u transfer_id,
out o transfer_path);
PullRawEx(in s url,
in s local_name,
in s class,
in s verify_mode,
in t flags,
out u transfer_id,
out o transfer_path);
PullOci(in s ref,
in s local_name,
in s class,
in t flags,
out u transfer_id,
out o transfer_path);
ListTransfers(out a(usssdo) transfers);
ListTransfersEx(in s class,
in t flags,
out a(ussssdo) transfers);
CancelTransfer(in u transfer_id);
ListImages(in s class,
in t flags,
out a(ssssbtttttt) images);
signals:
TransferNew(u transfer_id,
o transfer_path);
TransferRemoved(u transfer_id,
o transfer_path,
s result);
};
interface org.freedesktop.DBus.Peer { ... };
interface org.freedesktop.DBus.Introspectable { ... };
interface org.freedesktop.DBus.Properties { ... };
};
الطرق¶
ImportTar()/ImportTarEx() و ImportRaw()/ImportRawEx() تستورد صورة قرص وتضعها في دليل الصور. يجب أن تشير الوسيطة الأولى إلى واصف ملف (مفتوح للقراءة) يشير إلى ملف tar أو raw المراد استيراده. يجب أن يشير إلى ملف على القرص، أو أنبوب، أو مقبس. عند استخدام ImportTar()/ImportTarEx()، يجب أن يشير واصف الملف إلى ملف tar، مضغوط اختيارياً باستخدام gzip(1) أو zstd(1) أو bzip2(1) أو xz(1). يكتشف systemd-importd نظام الضغط المستخدم (إن وجد) آلياً. عند استخدام ImportRaw()/ImportRawEx()، يجب أن يشير واصف الملف إلى صورة قرص raw أو qcow2 تحتوي على تسمية قرص MBR أو GPT، مضغوطة اختيارياً أيضًا باستخدام gzip أو zstd أو bzip2 أو xz. في كلتا الحالتين، إذا تم تحديد الملف كواصف ملف على القرص، يتم إنشاء معلومات التقدم لعملية الاستيراد (لأننا في هذه الحالة نعرف الحجم الإجمالي على القرص). إذا تم تحديد مقبس أو أنبوب، فإن معلومات التقدم غير متوفرة. تتبع وسيطة واصف الملف اسم محلي للصورة. يجب أن يكون هذا الاسم مناسباً كاسم مضيف وسيستخدم لتسمية الصورة المستوردة تحت /var/lib/machines/. يتم وضع استيراد tar كشجرة دليل أو مجلد فرعي btrfs(8) تحت دليل الصور بالاسم المحدد دون إضافة لاحقة. يتم وضع استيراد raw كملف في دليل الصور مع إضافة اللاحقة .raw. في حالة ImportTar()/ImportRaw()، إذا كانت وسيطة force صحيحة، يتم إزالة أي صورة موجودة مسبقاً بنفس الاسم قبل بدء العملية. وإلا، تفشل العملية إذا كانت صورة بنفس الاسم موجودة بالفعل. تتحكم وسيطة read_only في إنشاء صورة قابلة للكتابة أو للقراءة فقط. في حالة ImportTarEx()/ImportRawEx()، يتم توفير هذه العلامات المنطقية عبر معلمة flags 64 بت بدلاً من ذلك، مع تعيين البت 0 لمعلمة force، والبت 1 لـ read_only. تحدد معلمة class فئة الصورة، وتأخذ إحدى القيم "machine" أو "portable" أو "sysext" أو "confext". تعود جميع الطرق الأربع فوراً بعد بدء الاستيراد، مع استمرار نقل الاستيراد. تُرجع زوجاً من معرف النقل ومسار الكائن، والذي يمكن استخدامه لاسترداد معلومات التقدم حول النقل أو لإلغائه. معرف النقل هو معرف رقمي بسيط، ومسار الكائن يشير إلى كائن org.freedesktop.import1.Transfer، انظر أدناه. استمع إلى إشارة TransferRemoved() لمعرف النقل لاكتشاف اكتمال النقل. يكون كائن النقل المُعاد مفيداً لتحديد التقدم الحالي أو مخرجات السجل لعملية الاستيراد الجارية.
تنقّذ الدالتان ExportTar()/ExportTarEx() و ExportRaw()/ExportRaw() العملية العكسية، ويمكن استخدامهما لتصدير صورة نظام لوضعها في ملف tar أو صورة raw خام. تأخذان اسم الآلة المراد تصديرها كمعامل أول، يليه واصف ملف (مفتوح للكتابة) حيث سيُكتب ملف tar أو raw. يمكن أن يشير إما إلى ملف على القرص أو إلى أنبوب/مقبس. ويحدد المعامل الثالث صيغة الضغط التي ستُكتب بها الصورة. ويأخذ أحد القيم التالية: "uncompressed" (غير مضغوط)، أو "xz"، أو "bzip2"، أو "gzip"، أو "zstd"، بناءً على مخطط الضغط المطلوب. ستكون الصورة المكتوبة في واصف الملف المحدد ملف tar في حالة ExportTar()/ExportTarEx() أو صورة قرص خام في حالة ExportRaw()/ExportRawEx(). لاحظ أنه لا يمكن حاليًا تصدير صور الأقراص الخام كملفات tar، والعكس صحيح. قد يُرفع هذا القيد في النهاية. تعيد الدالة معرف نقل ومسار كائن لإلغاء عملية التصدير أو تتبعها، على غرار ImportTar()/ImportTarEx() أو ImportRaw()/ImportRawEx() كما هو موضح أعلاه. تتوقع الدالتان ExportTarEx()/ExportRawEx() فئة الصورة كمعامل إضافي، بالإضافة إلى معامل أعلام بعرض 64 بت يجب تحديده حاليًا كصفر.
يمكن استخدام PullTar()/PullTarEx() و PullRaw()/PullRawEx() لتنزيل صورة نظام والتحقق منها واستيرادها من عنوان URL. تأخذ هذه الدوال معامل عنوان URL يجب أن يشير إلى ملف tar أو raw عبر بروتوكولات "http://" أو "https://"، وقد يكون مضغوطًا باستخدام xz أو bzip2 أو gzip أو zstd. المعامل الثاني هو اسم محلي للصورة. يجب أن يكون مناسبًا كاسم مستضيف، على غرار المعامل المطابق في دالات ImportTar()/ImportTarEx() و ImportRaw()/ImportRawEx() أعلاه. يشير المعامل الثالث إلى وضع التحقق من الصورة. يمكن أن يكون أحد القيم "no" أو "checksum" أو "signature". حيث يعطل الوضع "no" أي نوع من التحقق من الصورة؛ ويبحث الوضع "checksum" عن ملف SHA256SUM بجوار الصورة المنزلة ويتحقق من أي قيمة مجزأة لـ SHA256 في ذلك الملف مقابل الصورة؛ ويفعل الوضع "signature" الشيء نفسه ولكنه يحاول أيضًا استيثاق ملف SHA256SUM عبر البلاغ gpg(8) أولاً. في حالة PullTar()/PullRaw()، يشير المعامل الأخير إلى ما إذا كانت ستُستبدل صورة قد تكون موجودة مسبقًا وتحمل الاسم المحلي نفسه (إذا كانت القيمة "true")، أو الفشل (إذا كانت "false"). وفي حالة PullTarEx()/PullRawEx()، فإن المعامل الأخير هو معامل أعلام بعرض 64 بت، حيث يتحكم البت 0 في علم القوة "force"، والبت 1 هو علم القراءة فقط "read_only" الذي يتحكم في ما إذا كانت الصورة المنشأة ستُعلم كقراءة فقط، والبت 2 هو علم الاحتفاظ بالتنزيل "keep_download" الذي يشير إلى ما إذا كان سيُحتفظ بنسخة أصلية للقراءة فقط من الصورة المنزلة، بالإضافة إلى النسخة المحلية للصورة. تتوقع المتغيرات ..._Ex() أيضًا سلسلة فئة الصورة (كما هو موضح أعلاه). ومثل استدعاءات الاستيراد والتصدير أعلاه، تعيد هذه الاستدعاءات زوجًا يتكون من معرف النقل ومسار الكائن للتنزيل الجاري.
تشبه الدالة PullOci() الدالتين PullTarEx() أو PullRawEx() ويمكن استخدامها لتنزيل واستيراد صورة حاوية OCI من سجل OCI. وتأخذ مرجع حاوية OCI كمعامل. المعامل الثاني هو اسم محلي للصورة (والذي سيُنشأ كدليل systemd.mstack(7) يشير إلى طبقات OCI). يجب أن يكون مناسبًا كاسم مستضيف، على غرار المعامل المطابق لدالات PullTar()/PullTarEx() و PullRaw()/PullRawEx() أعلاه. المعامل الأخير هو معامل أعلام بعرض 64 بت، حيث يتحكم البت 0 في علم القوة "force"، والبت 1 هو علم القراءة فقط "read_only" الذي يتحكم في ما إذا كانت الصورة المنشأة ستُعلم كقراءة فقط. ومثل استدعاءات السحب أعلاه، يعيد هذا الاستدعاء زوجًا يتكون من معرف النقل ومسار الكائن للتنزيل الجاري.
تشبه الدالتان ImportFileSystem()/ImportFileSystemEx() الدالتين ImportTar()/ImportTarEx() ولكنهما تستوردان شجرة دليل. يجب أن يشير المعامل الأول إلى واصف ملف دليل للهرمية المصدر المراد استيرادها.
تعيد الدالتان ListTransfers()/ListTransfersEx() قائمة بعمليات الاستيراد أو التصدير أو التنزيل الجارية والتي أُنشئت باستخدام الاستدعاءات الستة الموضحة أعلاه. وتعيدان مصفوفة من البنى التي تتكون من معرف النقل الرقمي، وسلسلة نصية تشير إلى العملية (إحدى القيم التالية: "import-tar"، أو "import-raw"، أو "export-tar"، أو "export-raw"، أو "pull-tar"، أو "pull-raw")، وسلسلة نصية تصف الملف البعيد (في حالة عمليات التنزيل يكون هذا عنوان URL المصدر، وفي حالة عمليات الاستيراد/التصدير تكون هذه سلسلة نصية قصيرة تصف واصف الملف الممرر)، وسلسلة نصية تحتوي على اسم صورة الآلة المحلية، وفئة الصورة (فقط في حالة ListTransfersEx()؛ إحدى القيم التالية: "machine"، أو "portable"، أو "sysext"، أو "confext")، وقيمة تقدم بين 0.0 (لـ 0%) و 1.0 (لـ 100%)، بالإضافة إلى مسار كائن النقل.
يمكن استخدام CancelTransfer() لإلغاء عملية استيراد أو تصدير أو تنزيل جارية. ما عليك سوى تحديد معرف النقل لإلغاء العملية الجارية.
تعيد الدالة ListImages() قائمة بالصور المثبتة حاليًا. وتأخذ سلسلة نصية لفئة الصورة ومعامل أعلام. فئة الصورة إما أن تكون سلسلة فارغة أو تحدد واحدة من فئات الصور الأربع، والتي ستصفي بناءً عليها بعد ذلك. يجب أن يكون معامل الأعلام صفرًا في هذا الوقت. وتعيد مصفوفة من العناصر، يصف كل منها صورة واحدة. حقول العناصر مرتبة كالتالي: فئة الصورة، واسم الصورة المحلية، ونوع الصورة، ومسار الصورة، وعلم القراءة فقط، ووقت الإنشاء والتعديل (بالميكروثانية منذ حقبة UNIX)، بالإضافة إلى استخدام القرص الحالي بالبايت (الإجمالي والحصري على حد سواء)، فضلاً عن أي حد للحجم بالبايت معين على الصورة (الإجمالي والحصري على حد سواء).
الإشارات¶
يُولّد الإشعار TransferNew() في كل مرة يبدأ فيها نقل جديد باستخدام استدعاءات الاستيراد أو التصدير أو التنزيل الموضحة أعلاه. ويحمل معرف النقل ومسار الكائن اللذين أُنشئا للتو.
يُرسل الإشعار TransferRemoved() في كل مرة ينتهي فيها النقل، أو يُلغى، أو يفشل. ويحمل أيضًا معرف النقل ومسار الكائن، تليهما سلسلة نصية تشير إلى نتيجة العملية، وهي إحدى القيم التالية: "done" (عند النجاح)، أو "canceled" (ملغاة)، أو "failed" (فاشلة).
كائن النقل¶
node /org/freedesktop/import1/transfer/_1 {
interface org.freedesktop.import1.Transfer {
methods:
Cancel();
signals:
LogMessage(u priority,
s line);
ProgressUpdate(d progress);
properties:
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly u Id = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Local = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Remote = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Type = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Verify = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly d Progress = ...;
};
interface org.freedesktop.DBus.Peer { ... };
interface org.freedesktop.DBus.Introspectable { ... };
interface org.freedesktop.DBus.Properties { ... };
};
الطرق¶
يمكن استخدام الدالة Cancel() لإلغاء النقل. ولا تأخذ أي معاملات. تتطابق هذه الدالة تمامًا مع الدالة CancelTransfer() في واجهة المدير (انظر أعلاه)، ولكنها تُكشف في كائن النقل نفسه بدلاً من أخذ معرف النقل.
خصائص¶
تكشف الخاصية Id عن معرف النقل الرقمي لكائن النقل.
تكشف الخصائص Local و Remote و Type عن اسم الحاوية المحلية لهذا النقل، والمصدر البعيد (في حالة التنزيل: عنوان URL، في حالة الاستيراد/التصدير: سلسلة تصف واصف الملف المُمرر)، ونوع العملية (انظر طريقة ListTransfer() الخاصة بالمدير أعلاه لشرح القيم الممكنة).
تكشف الخاصية Verify عن إعداد التحقق المُختار وهي مُعرّفة فقط لعمليات التنزيل (انظر أعلاه).
تكشف الخاصية Progress عن التقدم الحالي للنقل كقيمة بين 0.0 و 1.0. لعرض شريط تقدم على الشاشة، نوصي باستعلام هذه القيمة على فترات منتظمة، على سبيل المثال كل 500 مللي ثانية تقريبًا.
الإشارات¶
يُصدر الإشارة LogMessage() لرسائل السجل الناتجة عن نقل. تحمل زوجًا من عدد صحيح لمستوى سجل النظام وسلسلة سجل.
يُصدر الإشارة ProgressUpdate() على فترات منتظمة عندما تتوفر معلومات تقدم تنزيل جديدة لنقل. تحمل رقم فاصلة عائمة مزدوج الدقة بين 0.0 و 1.0 يشير إلى تقدم النقل.
أمثلة¶
مثال 1. استبصار org.freedesktop.import1.Manager على الناقل
$ gdbus introspect --system \
--dest org.freedesktop.import1 \
--object-path /org/freedesktop/import1
مثال 2. استبصار org.freedesktop.import1.Transfer على الناقل
$ gdbus introspect --system \
--dest org.freedesktop.import1 \
--object-path /org/freedesktop/import1/transfer/_1
الإصدار¶
تتبع واجهات D-Bus هذه إرشادات إصدار الواجهة المعتادة[1].
التاريخ¶
كائن المدير¶
أُضيفت ImportTarEx() و ImportRawEx() و ImportFileSystemEx() و ExportTarEx() و ExportRawEx() و PullTarEx() و PullRawEx() و ListTransfersEx() و ListImages() في الإصدار 256.
أُضيفت PullOci() في الإصدار 260.
كائنات النقل¶
أُضيفت ProgressUpdate() في الإصدار 256.
انظر أيضًا¶
ملاحظات¶
- 1.
- إرشادات إصدارات الواجهة المعتادة
ترجمة¶
تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي <zayed.alsaidi@gmail.com>
هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.
إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: kde-l10n-ar@kde.org.
| systemd 260.1 |