نام (NAME)

org.freedesktop.portable1 - رابط دی‌باس سرویس مدیریت سرویس‌های پرتابل سیستم‌دی (systemd-portabled)

توضیحات (DESCRIPTION)

systemd-portabled.service(8) یک سرویس سیستمی است که می‌تواند برای متصل کردن (attach)، جدا کردن (detach) و بازرسی سرویس‌های پرتابل به کار رود. این صفحه رابط کاربری D-Bus را شرح می‌دهد.

شیء MANAGER (THE MANAGER OBJECT)

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

node /org/freedesktop/portable1 {
  interface org.freedesktop.portable1.Manager {
    methods:
      GetImage(in  s image,
               out o object);
      ListImages(out a(ssbtttso) images);
      GetImageOSRelease(in  s image,
                        out a{ss} os_release);
      GetImageMetadata(in  s image,
                       in  as matches,
                       out s image,
                       out ay os_release,
                       out a{say} units);
      GetImageMetadataWithExtensions(in  s image,
                                     in  as extensions,
                                     in  as matches,
                                     in  t flags,
                                     out s image,
                                     out ay os_release,
                                     out a{say} extensions,
                                     out a{say} units);
      GetImageState(in  s image,
                    out s state);
      GetImageStateWithExtensions(in  s image,
                                  in  as extensions,
                                  in  t flags,
                                  out s state);
      AttachImage(in  s image,
                  in  as matches,
                  in  s profile,
                  in  b runtime,
                  in  s copy_mode,
                  out a(sss) changes);
      AttachImageWithExtensions(in  s image,
                                in  as extensions,
                                in  as matches,
                                in  s profile,
                                in  s copy_mode,
                                in  t flags,
                                out a(sss) changes);
      DetachImage(in  s image,
                  in  b runtime,
                  out a(sss) changes);
      DetachImageWithExtensions(in  s image,
                                in  as extensions,
                                in  t flags,
                                out a(sss) changes);
      ReattachImage(in  s image,
                    in  as matches,
                    in  s profile,
                    in  b runtime,
                    in  s copy_mode,
                    out a(sss) changes_removed,
                    out a(sss) changes_updated);
      ReattachImageWithExtensions(in  s image,
                                  in  as extensions,
                                  in  as matches,
                                  in  s profile,
                                  in  s copy_mode,
                                  in  t flags,
                                  out a(sss) changes_removed,
                                  out a(sss) changes_updated);
      RemoveImage(in  s image);
      MarkImageReadOnly(in  s image,
                        in  b read_only);
      SetImageLimit(in  s image,
                    in  t limit);
      SetPoolLimit(in  t limit);
    properties:
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly s PoolPath = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly t PoolUsage = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly t PoolLimit = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly as Profiles = ['...', ...];
  };
  interface org.freedesktop.DBus.Peer { ... };
  interface org.freedesktop.DBus.Introspectable { ... };
  interface org.freedesktop.DBus.Properties { ... };
};

متدها (Methods)

GetImage() می‌تواند برای دریافت مسیر شیء تصویر برای تصویری با نام مشخص‌شده به کار رود.

ListImages() آرایه‌ای از تمام تصویرهای شناخته‌شدهٔ فعلی را بازمی‌گرداند. ساختارهای موجود در این آرایه شامل فیلدهای زیر هستند: نام تصویر، نوع، فلگ فقط‌خواندنی، زمان ایجاد، زمان تغییر، فضای فعلی دیسک، میزان استفاده و مسیر شیء تصویر.

GetImageOSRelease() اطلاعات انتشار سیستم‌عامل (OS release) یک تصویر را بازیابی می‌کند. این متد آرایه‌ای از جفت‌های کلید-مقدار خوانده‌شده از فایل os-release(5) در داخل تصویر را بازمی‌گرداند و برای شناسایی سیستم‌عامل مورد استفاده در یک سرویس پرتابل مفید است.

GetImageMetadata() متاداده‌های مرتبط با یک تصویر را بازیابی می‌کند. این متد نام تصویر، محتوای os-release(5) تصویر را در قالب یک آرایه بایت (قابل استریم)، و فهرستی از واحدهای پرتابل موجود در تصویر را در قالب یک رشته (نام واحد) و آرایه‌ای از بایت‌ها شامل محتوا بازمی‌گرداند.

GetImageMetadataWithExtensions() متاداده‌های مرتبط با یک تصویر را بازیابی می‌کند. این متد یک ابرمجموعه از GetImageMetadata() است که فهرستی از اکستنشن‌ها (افزونه‌ها) را به عنوان پارامتر ورودی اضافه دارد، که این اکستنشن‌ها از طریق AttachImageWithExtensions() روی تصویر اصلی سوار (overlay) شده‌اند. مسیر هر اکستنشن و یک آرایه بایت شامل محتوای فایل extension-release مربوطه بازگردانده می‌شود؛ برای هر اکستنشنِ نام‌برده در آرگومان‌های ورودی، یک چنین ساختاری بازگردانده خواهد شد.

GetImageState() وضعیت تصویر را به صورت یکی از رشته‌های زیر بازمی‌یابد:

•detached

•attached

•attached-runtime

•enabled

•enabled-runtime

•running

•running-runtime

GetImageStateWithExtensions() یک ابرمجموعه از GetImageState() است، همراه با پشتیبانی افزوده از فهرستی از اکستنشن‌ها به عنوان پارامترهای ورودی، که در صورتی که تصویر به آن روش خاص متصل شده باشد، برای استعلام وضعیت لازم است. پارامتر flags در حال حاضر بلااستفاده بوده و برای اهداف آینده رزرو شده است.

AttachImage() یک تصویر پرتابل را به سیستم متصل می‌کند. این متد یک مسیر یا نام تصویر، فهرستی از رشته‌ها که برای جستجوی فایل‌های واحد (unit files) در داخل تصویر استفاده می‌شوند (تطابق جزئی یا کامل)، یک رشته که نشان می‌دهد از کدام پروفایل پرتابل برای تصویر استفاده شود (برای فهرستی از پروفایل‌های موجود به ویژگی Profiles مراجعه کنید)، یک مقدار بولی که مشخص می‌کند آیا تصویر فقط برای نشست بوت فعلی متصل شود یا خیر، و یک رشته که نشان‌دهندهٔ حالت کپی ترجیحی است (اینکه تصویر کپی شود یا فقط پیوند نمادین/symlink ایجاد گردد) با مقادیر ممکن زیر را دریافت می‌کند:

•(empty)

•copy

•symlink

•mixed

اگر یک رشتهٔ خالی ارسال شود، پرونده‌های drop-in پروفایل امنیتی و تصویرها به‌صورت پیوند نمادین (symlink) متصل می‌شوند در حالی که فایل‌های واحد کپی خواهند شد؛ مقدار copy کپی می‌کند، symlink در صورت امکان پیوند زدن را ترجیح می‌دهد (برای مثال: یک واحد باید از یک تصویر کپی شود)، و mixed پیوند زدن منابع متعلق به سیستم‌عامل (مانند پروفایل پرتابل واقع در درخت /usr/ میزبان) را ترجیح می‌دهد اما منابع متعلق به تصویر پرتابل (مانند فایل‌های واحد و تصویرها) را کپی می‌کند. این متد فهرستی از تغییرات اعمال‌شده روی سیستم را بازمی‌گرداند (به‌عنوان مثال، کدام واحد اضافه شده و اکنون به‌عنوان یک سرویس سیستمی در دسترس است). هر تغییر به‌صورت یک سه‌تایی از رشته‌ها نمایش داده می‌شود: نوع تغییر اعمال‌شده، مسیری که تغییر روی آن اعمال شده، و منبع (در صورت وجود). نوع تغییر اعمال‌شده یکی از مقادیر ممکن زیر خواهد بود:

•copy

•symlink

•write

•mkdir

توجه داشته باشید که اگر واحدی که در تصویر وجود دارد از قبل روی سیستم موجود باشد، تصویر نمی‌تواند متصل شود. همچنین توجه داشته باشید که این متد تنها پس از تکمیل تمام عملیات‌های ذکرشده بازمی‌گردد، و با توجه به حجم ورودی/خروجی (I/O) درگیر، ممکن است مدتی طول بکشد.

به جای مسیر تصویر، می‌توان یک دایرکتوری دارای نسخهٔ ".v/" مشخص کرد؛ برای جزئیات به systemd.v(7) مراجعه کنید.

به جای مسیر دایرکتوری، می‌توان یک دایرکتوری دارای نسخهٔ ".v/" مشخص کرد؛ برای جزئیات به systemd.v(7) مراجعه کنید.

AttachImageWithExtensions() یک تصویر پرتابل را به سیستم متصل می‌کند. این متد یک ابرمجموعه از AttachImage() است با این تفاوت که فهرستی از اکستنشن‌ها را به عنوان پارامتر ورودی اضافه دارد، که روی تصویر اصلی سوار (overlay) می‌شوند. هنگامی که از این متد استفاده می‌شود، جدا کردن باید با ارسال همان آرگومان‌ها از طریق متد DetachImageWithExtensions() انجام شود. برای جزئیات بیشتر در مورد این قابلیت، مدخل MountImages= در systemd.exec(5) و systemd-sysext(8) را ببینید.

DetachImage() یک تصویر پرتابل را از سیستم جدا می‌کند. این متد مسیر یا نام یک تصویر و یک مقدار بولی را دریافت می‌کند که مشخص می‌سازد آیا تصویری که باید جدا شود، تنها برای نشست بوت فعلی متصل شده بود یا به صورت دائمی. این متد فهرستی از تغییرات اعمال‌شده روی سیستم را بازمی‌گرداند (برای مثال، کدام واحد حذف شده و دیگر به عنوان یک سرویس سیستمی در دسترس نیست). هر تغییر به صورت یک سه‌تایی از رشته‌ها نمایش داده می‌شود: نوع تغییر اعمال‌شده، مسیری که تغییر روی آن اعمال شده، و منبع (در صورت وجود). نوع تغییر اعمال‌شده یکی از مقادیر ممکن زیر خواهد بود:

•unlink

توجه داشته باشید که اگر واحدی که در تصویر وجود دارد در حال اجرا باشد، تصویر نمی‌تواند جدا شود. همچنین توجه داشته باشید که این متد تنها پس از تکمیل تمام عملیات‌های ذکرشده بازمی‌گردد، و با توجه به حجم ورودی/خروجی (I/O) درگیر، ممکن است مدتی طول بکشد.

DetachImageWithExtensions() یک تصویر پرتابل را از سیستم جدا می‌کند. این متد یک ابرمجموعه از DetachImage() است، با این تفاوت که فهرستی از اکستنشن‌ها را به عنوان پارامتر ورودی اضافه دارد که از طریق AttachImageWithExtensions() روی تصویر اصلی سوار شده بودند.

ReattachImage() اثرات متد AttachImage() و متد DetachImage() را با هم ترکیب می‌کند. تفاوت در این است که اتصال مجدد (reattach) یک تصویر در حالی که یک یا چند واحد آن در حال اجرا هستند مجاز است. در صورتی که هیچ تصویر منطبقی متصل نشده باشد، عملیات اتصال مجدد با شکست مواجه خواهد شد. پارامترهای ورودی با متد AttachImage() مطابقت دارند، و پارامترهای بازگشتی ترکیبی از پارامترهای بازگشتی متد DetachImage() (آرایه اول، واحدهایی که حذف شدند) و متد AttachImage() (آرایه دوم، واحدهایی که به‌روزرسانی یا اضافه شدند) هستند.

ReattachImageWithExtensions() یک تصویر پرتابل را مجدداً به سیستم متصل می‌کند. این متد یک ابرمجموعه از ReattachImage() است، با افزودن فهرستی از اکستنشن‌ها به عنوان پارامتر ورودی که روی تصویر اصلی سوار خواهند شد. برای جزئیات بیشتر در مورد این قابلیت، مدخل MountImages= در systemd.exec(5) و systemd-sysext(8) را ببینید.

RemoveImage() تصویر با نام مشخص‌شده را حذف می‌کند.

MarkImageReadOnly() وضعیت فلگ فقط‌خواندنی یک تصویر را تغییر می‌دهد (روشن/خاموش می‌کند).

SetPoolLimit() یک سقف سهمیهٔ کلی (quota limit) برای استخر (pool) تصویرها تعیین می‌کند.

SetImageLimit() یک سقف سهمیه به ازای هر تصویر تعیین می‌کند.

متدهای AttachImageWithExtensions()، DetachImageWithExtensions() و ReattachImageWithExtensions() به جای مقادیر بولی، گزینه‌ها را به صورت فلگ دریافت می‌کنند تا امکان گسترش‌پذیری فراهم شود. SD_SYSTEMD_PORTABLE_FORCE_ATTACH بررسی‌های امنیتی مبنی بر عدم اجرای واحدها هنگام متصل یا جدا شدن تصویر را دور می‌زند. SD_SYSTEMD_PORTABLE_FORCE_EXTENSION بررسیِ مطابقت فایل extension-release.NAME در تصویر اکستنشن با نام تصویر را دور می‌زند. آن‌ها به شرح زیر تعریف شده‌اند:

#define SD_SYSTEMD_PORTABLE_RUNTIME            (UINT64_C(1) << 0)
#define SD_SYSTEMD_PORTABLE_FORCE_ATTACH       (UINT64_C(1) << 1)
#define SD_SYSTEMD_PORTABLE_FORCE_EXTENSION    (UINT64_C(1) << 2)

ویژگی‌ها (Properties)

PoolPath مسیر سیستم پرونده را که تصویرها در آن نوشته می‌شوند مشخص می‌کند.

PoolUsage اندازهٔ استفادهٔ فعلی از استخر تصویرها را به بایت مشخص می‌کند.

PoolLimit سقف اندازهٔ استخر تصویرها را به بایت مشخص می‌کند.

Profiles پروفایل‌های زمان اجرای موجود برای سرویس‌های پرتابل را مشخص می‌کند.

شیء IMAGE (THE IMAGE OBJECT)

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

node /org/freedesktop/portable1 {
  interface org.freedesktop.portable1.Image {
    methods:
      GetOSRelease(out a{ss} os_release);
      GetMetadata(in  as matches,
                  out s image,
                  out ay os_release,
                  out a{say} units);
      GetMetadataWithExtensions(in  as extensions,
                                in  as matches,
                                in  t flags,
                                out s image,
                                out ay os_release,
                                out a{say} extensions,
                                out a{say} units);
      GetState(out s state);
      GetStateWithExtensions(in  as extensions,
                             in  t flags,
                             out s state);
      Attach(in  as matches,
             in  s profile,
             in  b runtime,
             in  s copy_mode,
             out a(sss) changes);
      AttachWithExtensions(in  as extensions,
                           in  as matches,
                           in  s profile,
                           in  s copy_mode,
                           in  t flags,
                           out a(sss) changes);
      Detach(in  b runtime,
             out a(sss) changes);
      DetachWithExtensions(in  as extensions,
                           in  t flags,
                           out a(sss) changes);
      Reattach(in  as matches,
               in  s profile,
               in  b runtime,
               in  s copy_mode,
               out a(sss) changes_removed,
               out a(sss) changes_updated);
      ReattachWithExtensions(in  as extensions,
                             in  as matches,
                             in  s profile,
                             in  s copy_mode,
                             in  t flags,
                             out a(sss) changes_removed,
                             out a(sss) changes_updated);
      Remove();
      MarkReadOnly(in  b read_only);
      SetLimit(in  t limit);
    properties:
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly s Name = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly s Path = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly s Type = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly b ReadOnly = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly t CreationTimestamp = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly t ModificationTimestamp = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly t Usage = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly t Limit = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly t UsageExclusive = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly t LimitExclusive = ...;
  };
  interface org.freedesktop.DBus.Peer { ... };
  interface org.freedesktop.DBus.Introspectable { ... };
  interface org.freedesktop.DBus.Properties { ... };
};

متدها (Methods)

متدهای زیر همان عملیات متناظر با متدهای روی شیء Manager را پیاده‌سازی می‌کنند (بالا را ببینید). با این حال، این متدها روی شیء تصویر عمل می‌کنند و بنابراین پارامتر نام تصویر را دریافت نمی‌کنند. فراخوانی مستقیم متدها روی شیء Manager این مزیت را دارد که نیازی به فراخوانی GetImage() برای دریافت شیء تصویر مربوط به یک نام تصویر خاص نیست. بنابراین فراخوانی متدها روی شیء Manager یک بهینه‌سازی در رفت‌وبرگشت (round trip) به شمار می‌آید. فهرست متدها:

•GetOSRelease()

•GetMetadata()

•GetMetadataWithExtensions()

•GetState()

•Attach()

•AttachWithExtensions()

•Detach()

•DetachWithExtensions()

•Reattach()

•ReattachWithExtensions()

•Remove()

•MarkReadOnly()