نام (NAME)

org.freedesktop.sysupdate1 - رابط کاربری D-Bus سرویس systemd-sysupdate

توضیحات (DESCRIPTION)

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

هشدار! این API در حال حاضر ناپایدار است و بنابراین بین نگارش‌های systemd دستخوش تغییرات ناسازگار (breaking changes) می‌شود.

رابط D-BUS (THE D-BUS INTERFACE)

شیء MANAGER (THE MANAGER OBJECT)

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

node /org/freedesktop/sysupdate1 {
  interface org.freedesktop.sysupdate1.Manager {
    methods:
      ListTargets(out a(sso) targets);
      ListJobs(out a(tsuo) jobs);
      ListAppStream(out as urls);
    signals:
      JobRemoved(t id,
                 o path,
                 i status);
  };
  interface org.freedesktop.DBus.Peer { ... };
  interface org.freedesktop.DBus.Introspectable { ... };
  interface org.freedesktop.DBus.Properties { ... };
};

متدها (Methods)

ListTargets() فهرستی از تمام هدف‌های به‌روزرسانی شناخته‌شده را بازمی‌گرداند. این متد آرایه‌ای از ساختارها شامل یک رشته نشان‌دهنده کلاس هدف (برای توضیح مقادیر ممکن، ویژگی Class شیء Target در زیر را ببینید)، یک رشته شامل نام هدف، و مسیر شیء هدف را بازمی‌گرداند.

ListJobs() فهرستی از تمام کارهای در حال انجام را بازمی‌گرداند. این متد آرایه‌ای از ساختارها شامل یک شناسه عددی کار، یک رشته نشان‌دهنده نوع کار (برای توضیح مقادیر ممکن، ویژگی Type شیء Job در زیر را ببینید)، میزان پیشرفت کار، و مسیر شیء کار را بازمی‌گرداند.

ListAppStream() آرایه‌ای از تمام نشانی‌های وب (URL) کاتالوگ appstream که این سرویس می‌شناسد را بازمی‌گرداند. برای جزئیات بیشتر، متد GetAppStream() شیء Target در زیر را ببینید.

سیگنال‌ها (Signals)

سیگنال JobRemoved() هر بار که یک کار پایان می‌یابد، لغو می‌شود یا با شکست مواجه می‌شود، ارسال می‌گردد. این سیگنال همچنین شناسه کار و مسیر شیء، و به دنبال آن یک کد وضعیت عددی را به همراه دارد. اگر وضعیت صفر باشد، کار با موفقیت انجام شده است. وضعیت مثبت باید به عنوان یک کد خروج (یعنی "EXIT_FAILURE") در نظر گرفته شود، و وضعیت منفی باید به عنوان یک کد خطای منفی به سبک errno (یعنی "-EINVAL") در نظر گرفته شود.

شیء TARGET (THE TARGET OBJECT)

یک هدف (target)، مؤلفه‌ای از سیستم است (یعنی خود میزبان، یک sysext، یک confext و غیره) که می‌تواند توسط systemd-sysupdate(8) به‌روزرسانی شود.

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

node /org/freedesktop/sysupdate1/target/host {
  interface org.freedesktop.sysupdate1.Target {
    methods:
      List(in  t flags,
           out as versions);
      Describe(in  s version,
               in  t flags,
               out s json);
      CheckNew(out s new_version);
      Acquire(in  s new_version,
              in  t flags,
              out s new_version,
              out t job_id,
              out o job_path);
      Install(in  s new_version,
              in  t flags,
              out s new_version,
              out t job_id,
              out o job_path);
      Vacuum(out u instances,
             out u disabled_transfers);
      GetAppStream(out as appstream);
      GetVersion(out s version);
      ListFeatures(in  t flags,
                   out as features);
      DescribeFeature(in  s feature,
                      in  t flags,
                      out s json);
      SetFeatureEnabled(in  s feature,
                        in  i enabled,
                        in  t flags);
    properties:
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly s Class = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly s Name = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly s Path = '...';
  };
  interface org.freedesktop.DBus.Peer { ... };
  interface org.freedesktop.DBus.Introspectable { ... };
  interface org.freedesktop.DBus.Properties { ... };
};

متدها (Methods)

List() فهرستی از نگارش‌های موجود برای این هدف را بازمی‌گرداند. گزینه‌های اضافی می‌توانند از طریق آرگومان flags ارسال شوند. فلگ‌های معتبر به شرح زیر تعریف شده‌اند:

#define SD_SYSUPDATE_OFFLINE    (UINT64_C(1) << 0)

هنگامی که SD_SYSUPDATE_OFFLINE تنظیم شده باشد، این متد تنها نگارش‌هایی را بازمی‌گرداند که به صورت محلی نصب شده‌اند. در غیر این صورت، این متد متاداده را از شبکه دریافت کرده و تمامی نگارش‌های موجود برای این هدف را بازمی‌گرداند. برای پرس‌وجوی اطلاعات بیشتر درباره هر نگارش بازگردانده‌شده توسط این متد، از Describe() استفاده کنید.

Describe() تمامی اطلاعات شناخته‌شده درباره یک نگارش معین را به صورت یک شیء JSON بازمی‌گرداند. آرگومان version برای ارسال نگارشی که باید توصیف شود استفاده می‌شود. گزینه‌های اضافی می‌توانند از طریق آرگومان flags ارسال شوند. این متد از همان فلگ‌های List() پشتیبانی می‌کند. شیء JSON بازگردانده‌شده حاوی چندین کلید شناخته‌شده است. ممکن است در آینده کلیدهای بیشتری اضافه شوند. کلیدهای شناخته‌شده فعلی به شرح زیر هستند:

"version"

رشته‌ای شامل شماره نگارش.

"newest"

یک مقدار بولی که نشان می‌دهد آیا این نگارش، جدیدترین نگارش موجود برای هدف است یا خیر.

"available"

یک مقدار بولی که نشان می‌دهد آیا این نگارش برای بارگیری موجود است یا خیر.

"installed"

یک مقدار بولی که نشان می‌دهد آیا این نگارش به صورت محلی نصب شده است یا خیر.

"obsolete"

یک مقدار بولی که نشان می‌دهد آیا این نگارش از نظر سرویس منسوخ تلقی شده و بنابراین نصب آن ممنوع است یا خیر.

"protected"

یک مقدار بولی که نشان می‌دهد آیا این نگارش از حذف شدن توسط عملیات Vacuum() معاف است یا خیر.

"incomplete"

یک مقدار بولی که نشان می‌دهد آیا این نگارش ناقص است یا خیر، به این معنی که برخی پرونده‌ها را کم دارد. توجه داشته باشید که فقط نگارش‌های ناقصِ نصب‌شده توسط سرویس ارائه می‌شوند؛ نگارش‌هایی که در سمت سرور ناقص هستند کاملاً نادیده گرفته می‌شوند. نگارش‌های ناقص را می‌توان با فراخوانی Acquire() و Install() روی آن نگارش، در محل تعمیر کرد.

"changelogUrls"

فهرستی از رشته‌ها که حاوی نشانی‌های وب قابل‌نمایش به کاربر برای گزارش تغییرات (change logs) مرتبط با این نگارش هستند.

CheckNew() بررسی می‌کند که آیا نگارش جدیدتری برای این هدف موجود است یا خیر. این متد متاداده را از شبکه دریافت می‌کند. اگر نگارش جدیدتری پیدا شود، این متد شماره نگارش را بازمی‌گرداند. اگر نگارش جدیدتری پیدا نشود، یک رشته خالی بازمی‌گرداند. برای پرس‌وجوی اطلاعات بیشتر درباره نگارش بازگردانده‌شده توسط این متد، از Describe() استفاده کنید.

Acquire() در صورت موجود بودن یک به‌روزرسانی برای این هدف، آن را بارگیری می‌کند. اگر یک new_version مشخص شده باشد، همان نگارش بارگیری می‌شود. در غیر این صورت، آخرین نگارش بارگیری می‌گردد. برای نصب به‌روزرسانی دریافت‌شده، Install() را فراخوانی کنید. آرگومان flags برای قابلیت گسترش در آینده اضافه شده است. در حال حاضر هیچ فلگی تعریف نشده است و این آرگومان باید روی "0" تنظیم شود. این متد هم متاداده و هم داده‌های بار کاری (payload) را از شبکه دریافت می‌کند.

Install() یک به‌روزرسانی از پیش دریافت‌شده را برای این هدف نصب می‌کند. اگر یک new_version مشخص شده باشد، با فرض اینکه قبلاً دریافت شده باشد، همان نگارش نصب می‌شود. در غیر این صورت، آخرین نگارش دریافت‌شده نصب خواهد شد. آرگومان flags برای قابلیت گسترش در آینده اضافه شده است. در حال حاضر هیچ فلگی تعریف نشده است و این آرگومان باید روی "0" تنظیم شود.

برخلاف تمامی متدهای دیگر در این رابط، Acquire() و Install() منتظر تکمیل کارهای خود نمی‌مانند. در عوض، به محض شروع کار، شناسه عددی و مسیر شیء کار را بازمی‌گردانند تا فراخواننده بتواند به تغییرات پیشرفت گوش فرا دهد یا عملیات را لغو کند. این متدها همچنین برای مواردی که فراخواننده هیچ نگارشی را مشخص نکرده است، نگارشی را که هدف به آن به‌روزرسانی خواهد شد بازمی‌گردانند. برای تشخیص زمان اتمام کار، به سیگنال JobRemoved() شیء Manager گوش فرا دهید.

Vacuum() نگارش‌های قدیمی نصب‌شده این هدف را پاک می‌کند تا فضا آزاد شود. این متد تعداد نمونه‌هایی را که حذف شده‌اند بازمی‌گرداند.

GetAppStream() فهرستی از نشانی‌های HTTP/HTTPS به پرونده‌های XML کاتالوگ appstream[1] این هدف را بازمی‌گرداند. اگر این هدف هیچ کاتالوگ appstream نداشته باشد، این متد یک فهرست خالی بازمی‌گرداند. این پرونده‌های کاتالوگ می‌توانند توسط مراکز نرم‌افزاری (مانند نرم‌افزار گنوم یا Discover در کی‌دی‌ای) برای ارائه متاداده‌های غنی درباره هدف شامل نام نمایشی، تغییرات، آیکون و موارد دیگر استفاده شوند. کاتالوگ‌های بازگردانده‌شده شامل متاداده خاص[2] خواهند بود تا به مرکز نرم‌افزار اجازه دهند کاتالوگ‌ها را به درستی با این هدف پیوند دهد.

GetVersion() نگارش فعلی این هدف را، در صورت وجود، بازمی‌گرداند. نگارش فعلی، جدیدترین نگارشی است که نصب شده است. توجه داشته باشید که این لزوماً همان نگارش بوت‌شده یا در حال استفاده هدف نیست. به عنوان مثال، در سیستم میزبان، نگارش بوت‌شده در بیشتر مواقع همان نگارش فعلی است، اما اگر به‌روزرسانی نصب شده و در انتظار راه‌اندازی مجدد باشد، به جای آن به نگارش فعلی تبدیل خواهد شد. می‌توانید نگارش بوت‌شده سیستم میزبان را از طریق IMAGE_VERSION در /etc/os-release استعلام کنید. اگر هدف هیچ نگارش فعلی نداشته باشد، این تابع یک رشته خالی بازمی‌گرداند.

ListFeatures() فهرستی از ویژگی‌های اختیاری این هدف را بر اساس شناسه بازمی‌گرداند. آرگومان flags برای قابلیت گسترش در آینده اضافه شده است و باید روی 0 تنظیم شود. اگر هدف هیچ ویژگی اختیاری نداشته باشد، این متد یک آرایه خالی بازمی‌گرداند.

DescribeFeature() تمامی اطلاعات شناخته‌شده درباره یک ویژگی اختیاری معین را بازمی‌گرداند. آرگومان feature برای ارسال شناسه ویژگی‌ای که باید توصیف شود استفاده می‌شود. آرگومان flags برای قابلیت گسترش در آینده اضافه شده است و باید روی 0 تنظیم شود. شیء JSON بازگردانده‌شده حاوی چندین کلید شناخته‌شده است. ممکن است در آینده کلیدهای بیشتری اضافه شوند. کلیدهای شناخته‌شده فعلی به شرح زیر هستند:

"name"

رشته‌ای شامل نام ویژگی.

"description"

یک رشته اختیاری که حاوی شرحی قابل‌نمایش به کاربر است که این ویژگی را مشخص می‌کند.

"enabled"

یک مقدار بولی که نشان می‌دهد آیا این ویژگی فعال است یا خیر.

"documentationUrl"

یک رشته اختیاری شامل یک نشانی وب HTTP/HTTPS قابل‌نمایش به کاربر برای مستندات مربوط به این ویژگی.

"appstreamUrl"

یک رشته اختیاری شامل یک نشانی وب HTTP/HTTPS به یک پرونده XML کاتالوگ appstream[1] حاوی متاداده درباره این ویژگی.

"transfers"

یک آرایه اختیاری از رشته‌ها که فهرست می‌کند چه تعاریف انتقالی به این ویژگی تعلق دارند.

SetFeatureEnabled() یک پرونده drop-in مناسب برای فعال یا غیرفعال کردن ویژگی اختیاری مشخص‌شده می‌نویسد. اگر enable صفر باشد، ویژگی غیرفعال می‌شود. اگر بزرگتر از صفر باشد، ویژگی فعال می‌شود. اگر کوچکتر از صفر باشد، ویژگی به پیشفرض توزیع بازنشانی می‌شود. آرگومان flags برای قابلیت گسترش در آینده اضافه شده است و باید روی 0 تنظیم شود. ویژگی نیازی به موجود بودن ندارد؛ این امر امکان مدیریت مناسب ویژگی‌های ماسک‌شده و تصمیم‌گیری‌های پیشگیرانه درباره ویژگی‌هایی را که قرار است در نسخه‌های آینده سیستم‌عامل ظاهر شوند فراهم می‌کند. پرونده drop-in نامی برابر با "50-systemd-sysupdate-enabled.conf" خواهد داشت. این متد تنها پرونده‌های پیکربندی را تغییر می‌دهد؛ برای اعمال واقعی تغییرات، کلاینت‌ها باید Acquire() و Install() را فراخوانی کنند. بسته به نیازهای دقیق کلاینت، می‌تواند سیستم را به آخرین نگارش موجود به‌روزرسانی کند، یا می‌تواند جدیدترین نصب موجود را در محل گسترش دهد (با ارسال نگارش بازگردانده‌شده توسط GetVersion()). در حال حاضر، این متد تنها با هدف "host" کار می‌کند.

ویژگی‌ها (Properties)

ویژگی Class کلاس این هدف را نشان می‌دهد که توصیف می‌کند کجا شمارش شده است. مقادیر ممکن عبارتند از: "machine" برای کانتینرها و ماشین‌های مجازی مدیریت‌شده توسط systemd-machined.service(8)، "portable" برای سرویس‌های پرتابل[3]، "sysext" برای اکستنشن‌های سیستم مدیریت‌شده توسط systemd-sysext(8)، "confext" برای اکستنشن‌های پیکربندی مدیریت‌شده توسط systemd-confext(8)، "component" برای مؤلفه‌های پذیرفته‌شده توسط گزینه --component= دستور systemd-sysupdate(8)، و "host" برای خود سیستم میزبان. حداکثر یک هدف دارای کلاس "host" خواهد بود.

ویژگی Path جزئیات بیشتری را درباره محل یافتن این هدف نشان می‌دهد. برای هدف‌های "machine"، "portable"، "extension"، و "confext"، این مقدار مسیر پرونده به ایمیج است. برای هدف‌های "component" و "host"، این مقدار نام یک دایرکتوری sysupdate.d(5) است.

ویژگی Name نام این هدف را نشان می‌دهد. توجه داشته باشید که نام در داخل یک کلاس یکتا است اما لزوماً بین کلاس‌های مختلف یکتا نیست. به عنوان مثال، داشتن هر دو هدف "portable" به نام "foobar" و هدف "extension" به نام "foobar" ممکن است، اما داشتن دو هدف "portable" با نام "foobar" امکان‌پذیر نیست.

امنیت (Security)

فراخوانی‌های متد در این سرویس از طریق polkit[4] احراز هویت می‌شوند.

متدهای List()، Describe()، و CheckNew() از کنش polkit به نام org.freedesktop.sysupdate1.check استفاده می‌کنند. به صورت پیشفرض، این کنش بدون احراز هویت مدیر سیستم مجاز است. لغو این متدها از کنش polkit به نام org.freedesktop.sysupdate1.cancel-check استفاده می‌کند. به صورت پیشفرض، این کنش لغو بدون احراز هویت مدیر سیستم مجاز است.

متدهای Acquire() و Install() هنگامی که نگارشی مشخص نشده باشد، از کنش polkit به نام org.freedesktop.sysupdate1.update استفاده می‌کنند. به صورت پیشفرض، این کنش بدون احراز هویت مدیر سیستم مجاز است. هنگامی که یک نگارش مشخص شده باشد، به جای آن از org.freedesktop.sysupdate1.update-to-version استفاده می‌شود. به صورت پیشفرض، این کنش جایگزین نیازمند احراز هویت مدیر سیستم است. لغو این متدها از کنش‌های polkit به نام org.freedesktop.sysupdate1.cancel-update و org.freedesktop.sysupdate1.cancel-update-to-version استفاده می‌کند. به صورت پیشفرض، این کنش‌های لغو بدون احراز هویت مدیر سیستم مجاز هستند.

Vacuum() از کنش polkit به نام org.freedesktop.sysupdate1.vacuum استفاده می‌کند. به صورت پیشفرض، این کنش نیازمند احراز هویت مدیر سیستم است. لغو این متد از کنش polkit به نام org.freedesktop.sysupdate1.cancel-vacuum استفاده می‌کند. به صورت پیشفرض، این کنش لغو بدون احراز هویت مدیر سیستم مجاز است.

SetFeatureEnabled() از کنش polkit به نام org.freedesktop.sysupdate1.manage-features استفاده می‌کند. به صورت پیشفرض، این کنش نیازمند احراز هویت مدیر سیستم است. لغو کردن برای این متد پشتیبانی نمی‌شود.

متدهای GetAppStream()، GetVersion()، ListFeatures()، و DescribeFeature() فاقد احراز هویت هستند و توسط هر کسی قابل فراخوانی می‌باشند. لغو کردن برای این متدها پشتیبانی نمی‌شود، یا همیشه بدون احراز هویت مدیر سیستم مجاز است.

تمام متدهایی که در این رابط فراخوانی می‌شوند، متغیرهای اضافی را به قوانین polkit ارائه می‌دهند. متغیر "class" حاوی کلاس هدفی است که عملیات روی آن انجام می‌شود، و "name" حاوی نام همان هدف است. علاوه بر این، هر متد آرگومان‌های خود را به قانون polkit ارائه می‌دهد. فلگ‌ها به شرح زیر نگاشت می‌شوند:

•SD_SYSUPDATE_OFFLINE → "update"

شیء JOB (THE JOB OBJECT)

یک کار (job)، عملیاتی در حال انجام است که توسط یکی از متدهای روی یک شیء Target آغاز شده است.

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

node /org/freedesktop/sysupdate1/job/_1 {
  interface org.freedesktop.sysupdate1.Job {
    methods:
      Cancel();
    properties:
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly t Id = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly s Type = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly b Offline = ...;
      readonly u Progress = ...;
  };
  interface org.freedesktop.DBus.Peer { ... };
  interface org.freedesktop.DBus.Introspectable { ... };
  interface org.freedesktop.DBus.Properties { ... };
};

متدها (Methods)

متد Cancel() می‌تواند برای لغو کار استفاده شود. این متد هیچ پارامتری دریافت نمی‌کند.

ویژگی‌ها (Properties)

ویژگی Id شناسه عددی شیء کار را نشان می‌دهد.

ویژگی Type نوع عملیات را نشان می‌دهد (یکی از: "list"، "describe"، "check-new"، "acquire"، "install"، "vacuum"، یا "describe-feature").

ویژگی Offline نشان می‌دهد که آیا کار مجاز به دسترسی به شبکه است یا خیر.

ویژگی Progress پیشرفت فعلی کار را به صورت مقداری بین 0 تا 100 نشان می‌دهد. این ویژگی تنها برای کارهای "acquire" و "install" موجود است؛ برای سایر کارها همیشه 0 است.

امنیت (Security)

Cancel() از کنش polkit متناظر با متدی که این کار را آغاز کرده است استفاده می‌کند. به عنوان مثال، تلاش برای لغو یک کار "list" نیازمند این است که polkit کنش org.freedesktop.sysupdate1.check را مجاز بداند.

مثال‌ها (EXAMPLES)

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

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

مثال ۲. درون‌نگری org.freedesktop.sysupdate1.Target در گذرگاه

$ gdbus introspect --system \
  --dest org.freedesktop.sysupdate1 \
  --object-path /org/freedesktop/sysupdate1/target/host

مثال ۳. درون‌نگری org.freedesktop.sysupdate1.Job در گذرگاه

$ gdbus introspect --system \
  --dest org.freedesktop.sysupdate1 \
  --object-path /org/freedesktop/sysupdate1/job/_1

سازگاری نسخه (VERSION COMPATIBILITY)

این رابط‌های D-Bus از دستورالعمل‌های معمول نسخه‌بندی رابط[5] پیروی می‌کنند.

تاریخچه (HISTORY)

شیء Manager

متدهای ListTargets()، ListJobs()، ListAppStream() و سیگنال JobRemoved() در نسخه ۲۵۷ اضافه شدند.

شیء Target

متدهای List()، Describe()، CheckNew()، Acquire()، Install()، Vacuum()، GetAppStream()، GetVersion()، ListFeatures()، DescribeFeature()، SetFeatureEnabled() و ویژگی‌های Class، Name و Path در نسخه ۲۵۷ اضافه شدند.