ORG.FREEDESKTOP.IMPORT1(5) org.freedesktop.import1 ORG.FREEDESKTOP.IMPORT1(5)

org.freedesktop.import1 - رابط کاربری D-Bus سرویس systemd-importd

systemd-importd.service(8) یک سرویس سیستمی است که می‌تواند برای درون‌ریزی (import)، برون‌ریزی (export) و بارگیری تصویرهای دیسک به کار رود. این تصویرها می‌توانند توسط ابزارهایی مانند systemd-nspawn(1) برای اجرای کانتینرهای محلی استفاده شوند. این سرویس به‌عنوان پسانه (backend) برای دستورهای importctl pull-raw، importctl pull-tar و دستورهای مرتبط استفاده می‌شود. این صفحه رابط کاربری D-Bus را شرح می‌دهد.

توجه داشته باشید که systemd-importd.service(8) بیشتر یک سرویس همراه و مکمل کوچک برای systemd-machined.service(8) است. از این رو، بسیاری از عملیات‌های مربوط به مدیریت و دستکاری تصویرهای کانتینر و ماشین مجازی محلی از طریق API رابط D-Bus سرویس systemd-machined در دسترس هستند، مقایسه کنید با org.freedesktop.machine1(5).

این سرویس رابط‌های زیر را روی شیء Manager در گذرگاه ارائه می‌دهد:

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 مقدار true داشته باشد، هر تصویر موجود قبلی با همان نام پیش از شروع عملیات حذف می‌شود. در غیر این صورت، اگر تصویری با همان نام از قبل وجود داشته باشد، عملیات با شکست مواجه می‌شود. آرگومان read_only کنترل می‌کند که آیا تصویری با قابلیت نوشتن یا فقط‌خواندنی ایجاد شود. در مورد ImportTarEx()/ImportRawEx() این فلگ‌های بولی از طریق یک پارامتر فلگ‌های ۶۴ بیتی ارائه می‌شوند، که در آن بیت ۰ به پارامتر force و بیت ۱ به پارامتر read_only نگاشت می‌شود. پارامتر class ردهٔ تصویر را مشخص می‌کند و یکی از مقادیر "machine"، "portable"، "sysext" یا "confext" را می‌پذیرد. هر چهار متد بلافاصله پس از آغاز درون‌ریزی بازمی‌گردند، در حالی که انتقال درون‌ریزی در پس‌زمینه در جریان است. آن‌ها یک جفت شامل شناسهٔ انتقال و مسیر شیء را برمی‌گردانند که می‌تواند برای دریافت اطلاعات پیشرفت دربارهٔ انتقال یا لغو آن استفاده شود. شناسهٔ انتقال یک شناسهٔ عددی ساده است و مسیر شیء به یک شیء org.freedesktop.import1.Transfer ارجاع می‌دهد؛ به زیر نگاه کنید. برای تشخیص اتمام یک انتقال، به سیگنال TransferRemoved() مربوط به شناسهٔ انتقال گوش دهید. شیء انتقال بازگردانده‌شده برای تعیین پیشرفت فعلی یا خروجی گزارش عملیات درون‌ریزی در حال انجام مفید است.

ExportTar()/ExportTarEx() و ExportRaw()/ExportRawEx() عملیات معکوس را پیاده‌سازی می‌کنند و می‌توانند برای برون‌ریزی یک تصویر سیستم و قرار دادن آن در یک تصویر tar یا raw به کار روند. آن‌ها نام ماشین مورد نظر برای برون‌ریزی را به‌عنوان پارامتر نخست دریافت می‌کنند و به دنبال آن یک توصیف‌گر فایل (باز شده برای نوشتن) قرار دارد که فایل tar یا raw در آن نوشته خواهد شد. این توصیف‌گر می‌تواند به فایلی روی دیسک یا یک لوله/سوکت ارجاع داشته باشد. آرگومان سوم قالبی را که تصویر باید با آن فشرده و نوشته شود مشخص می‌کند. این آرگومان بسته به طرح فشرده‌سازی مورد نیاز، یکی از مقادیر "uncompressed"، "xz"، "bzip2"، "gzip" یا "zstd" را می‌پذیرد. تصویر نوشته‌شده در توصیف‌گر فایل مشخص‌شده، در مورد ExportTar()/ExportTarEx() یک فایل tar و در مورد ExportRaw()/ExportRawEx() یک تصویر دیسک خام (raw) خواهد بود. توجه داشته باشید که در حال حاضر تصاویر دیسک خام را نمی‌توان به‌عنوان فایل tar برون‌ریزی کرد و بالعکس؛ این محدودیت ممکن است در آینده برداشته شود. این متدها همانند ImportTar()/ImportTarEx() یا ImportRaw()/ImportRawEx() که در بالا شرح داده شد، یک شناسهٔ انتقال و مسیر شیء برای لغو یا پیگیری عملیات برون‌ریزی برمی‌گردانند. ExportTarEx()/ExportRawEx() کلاس تصویر را به‌عنوان پارامتر اضافی، همراه با یک پارامتر فلگ‌های ۶۴ بیتی که در حال حاضر باید صفر مقداردهی شود، انتظار دارند.

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() آخرین آرگومان یک پارامتر فلگ‌های ۶۴ بیتی است، که در آن بیت ۰ فلگ "force" را کنترل می‌کند، بیت ۱ فلگ "read_only" است که تعیین می‌کند آیا تصویر ایجادشده باید فقط‌خواندنی علامت‌گذاری شود یا خیر، و بیت ۲ فلگ "keep_download" است که مشخص می‌کند آیا علاوه‌بر نسخهٔ محلی تصویر، باید یک نسخهٔ دست‌نخورده و فقط‌خواندنی از تصویر بارگیری‌شده نیز نگهداری شود یا خیر. انواع ..._Ex() همچنین یک رشتهٔ ردهٔ تصویر را انتظار دارند (همان‌طور که در بالا آمد). این فراخوانی‌ها نیز همانند فراخوانی‌های درون‌ریزی و برون‌ریزی بالا، یک جفت شامل شناسهٔ انتقال و مسیر شیء برای بارگیری در حال انجام برمی‌گردانند.

PullOci() مشابه PullTarEx() یا PullRawEx() است و می‌تواند برای بارگیری و درون‌ریزی یک تصویر کانتینر OCI از یک رجیستری OCI استفاده شود. این متد یک ارجاع کانتینر OCI را به‌عنوان آرگومان دریافت می‌کند. آرگومان دوم یک نام محلی برای تصویر است (که به‌عنوان دایرکتوری systemd.mstack(7) با ارجاع به لایه‌های OCI ایجاد خواهد شد). این نام باید برای یک نام میزبان مناسب باشد، مشابه با آرگومان متناظر در متدهای PullTar()/PullTarEx() و PullRaw()/PullRawEx() در بالا. آخرین آرگومان یک پارامتر فلگ‌های ۶۴ بیتی است، که در آن بیت ۰ فلگ "force" و بیت ۱ فلگ "read_only" را کنترل می‌کند که تعیین می‌نماید آیا تصویر ایجادشده باید فقط‌خواندنی علامت‌گذاری شود یا خیر. این فراخوانی نیز همانند فراخوانی‌های دریافت (pull) بالا، یک جفت شامل شناسهٔ انتقال و مسیر شیء برای بارگیری در حال انجام برمی‌گرداند.

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 (برای ۰٪) و 1.0 (برای ۱۰۰٪)، و همچنین مسیر شیء انتقال است.

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

ListImages() فهرستی از تصویرهای نصب‌شدهٔ کنونی را بازمی‌گرداند. این متد یک رشتهٔ ردهٔ تصویر و یک پارامتر فلگ‌ها را دریافت می‌کند. ردهٔ تصویر یا یک رشتهٔ خالی است یا یکی از چهار ردهٔ تصویر را مشخص می‌کند که بر اساس آن فیلتر خواهد شد. پارامتر فلگ‌ها در حال حاضر باید صفر باشد. این متد آرایه‌ای از آیتم‌ها را برمی‌گرداند که هر یک توصیف‌کنندهٔ یک تصویر هستند. فیلدهای هر آیتم به ترتیب عبارتند از: ردهٔ تصویر، نام محلی تصویر، نوع تصویر، مسیر تصویر، فلگ فقط‌خواندنی بودن، زمان ایجاد و آخرین تغییر (به میکروثانیه از مبدأ زمانی یونیکس - UNIX epoch)، همچنین میزان مصرف فعلی دیسک به بایت (هم به‌صورت کلی و هم اختصاصی)، و هرگونه سقف اندازه به بایت که برای تصویر تعیین شده است (هم کلی و هم اختصاصی).

سیگنال 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() روی رابط Manager است (بالا را ببینید)، با این تفاوت که به جای دریافت یک شناسهٔ انتقال، روی خود شیء Transfer ارائه شده است.

ویژگی Id شناسهٔ عددی انتقال مربوط به شیء انتقال را نشان می‌دهد.

ویژگی‌های Local، Remote و Type نام کانتینر محلی این انتقال، منبع راه دور (در صورت بارگیری: نشانی URL، در صورت درون‌ریزی/برون‌ریزی: یک رشته که توصیف‌گر فایل ارسال‌شده را توصیف می‌کند) و نوع عملیات را مشخص می‌کنند (برای توضیحات مربوط به مقادیر ممکن، متد ListTransfers() شیء Manager در بالا را ببینید).

ویژگی Verify تنظیمات اعتبارسنجی انتخاب‌شده را نشان می‌دهد و تنها برای عملیات بارگیری تعریف شده است (بالا را ببینید).

ویژگی Progress پیشرفت فعلی انتقال را به‌عنوان مقداری بین 0.0 و 1.0 نشان می‌دهد. برای نمایش نوار پیشرفت روی صفحه، توصیه می‌کنیم این مقدار در فواصل زمانی منظم، مثلاً هر ۵۰۰ میلی‌ثانیه یا در همین حدود، استعلام شود.

سیگنال LogMessage() برای پیام‌های گزارشی که توسط یک انتقال تولید می‌شوند منتشر می‌گردد. این سیگنال یک جفت شامل عدد صحیح سطح گزارش لاگ سیستم (syslog log level) و رشتهٔ پیام گزارش را حمل می‌کند.

سیگنال ProgressUpdate() در فواصل زمانی منظم، هنگامی که اطلاعات پیشرفت بارگیری جدید برای یک انتقال در دسترس قرار گیرد منتشر می‌شود. این سیگنال یک عدد ممیز شناور با دقت مضاعف (double) بین 0.0 و 1.0 را که نشان‌دهندهٔ پیشرفت انتقال است منتقل می‌کند.

مثال ۱. درون‌نگری org.freedesktop.import1.Manager روی گذرگاه

$ gdbus introspect --system \
  --dest org.freedesktop.import1 \
  --object-path /org/freedesktop/import1

مثال ۲. درون‌نگری 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() در نسخهٔ ۲۵۶ اضافه شدند.

PullOci() در نسخهٔ ۲۶۰ اضافه شد.

ProgressUpdate() در نسخهٔ ۲۵۶ اضافه شد.

systemd(1), systemd-importd.service(8), importctl(1)

1.
دستورالعمل‌های معمول نسخه‌بندی رابط
https://0pointer.de/blog/projects/versioning-dbus.html
systemd 261.2