LIBDNF5-ACTIONS(8) dnf5 LIBDNF5-ACTIONS(8)

libdnf5-actions - افزونه اقدامات libdnf5

این افزونه امکان تعریف اقداماتی را فراهم می‌کند که از طریق قلاب‌های بازخوانی (callback hooks) در libdnf5 اجرا می‌شوند. هر اقدام به یک بازخوانی مشخص متصل می‌شود. اقدامات برای بازخوانی‌های goal_resolved، pre_transaction و post_transaction می‌توانند یک قاعده پالایش (مشابه glob) روی NEVRA بسته یا فایل‌های بسته و همچنین ورودی یا خروجی بودن بسته تعریف کنند.

این افزونه پیکربندی استاندارد را گسترش نمی‌دهد؛ با این حال، فایل‌های اقدامات («actions») را می‌خواند.

فایل‌های اقدامات از دایرکتوری <libdnf5_plugins_config_dir>/actions.d/ خوانده می‌شوند. فقط فایل‌های دارای پسوند «.actions» خوانده می‌شوند. فایل‌های اقدامات به ترتیب لغوی (مرتب‌شده بر اساس نام فایل) با مقایسه مقادیر کاراکتری، بدون در نظر گرفتن محلی‌سازی (locale)، خوانده می‌شوند.

خطوط خالی و خطوطی که با کاراکتر «#» آغاز می‌شوند (خطوط توضیحات) نادیده گرفته می‌شوند.

هر خط غیرتوضیحی یک اقدام را تعریف می‌کند و از پنج بخش تشکیل شده که با دونقطه از یکدیگر جدا می‌شوند: callback_name:package_filter:direction:options:command.

callback_name

  • pre_base_setup
  • post_base_setup
  • repos_configured (در نسخه 1.0.0 اضافه شد)
  • repos_loaded (در نسخه 1.0.0 اضافه شد)
  • pre_add_cmdline_packages (در نسخه 1.0.0 اضافه شد)
  • post_add_cmdline_packages (در نسخه 1.0.0 اضافه شد)
  • goal_resolved (در نسخه 1.3.0 اضافه شد)
  • pre_transaction
  • post_transaction
یک قاعده پالایش (مشابه glob) که بر روی NEVRA بسته (همچنین به شکل‌های کوتاه‌شده) یا فایل‌های بسته اعمال می‌شود.

یک فیلتر خالی به معنای اجرای یک‌باره دستور بدون هیچ اطلاعاتی درباره بسته است. فیلتر «*» به معنای اجرای دستور به ازای هر بسته در تراکنش است که با فیلتر direction مطابقت داشته باشد. فیلتر تنها برای بازخوانی‌های goal_resolved، pre_transaction و post_transaction می‌تواند غیرخالی باشد.

بسته‌ها را بر اساس جهت آن‌ها (ورود به سیستم/خروج از سیستم) در یک تراکنش پالایش می‌کند. اگر خالی باشد، فیلتر اعمال نمی‌شود. این فیلتر تنها زمانی می‌تواند غیرخالی باشد که با یک package_filter غیرخالی ترکیب شده باشد.
  • in - بسته‌های ورودی به سیستم (تنزل، نصب، نصب مجدد، ارتقا)
  • out - بسته‌های خروجی از سیستم (ارتقایافته، تنزل‌یافته، مجدداً نصب‌شده، حذف‌شده، جایگزین/منسوخ‌شده)
گزینه‌ها با فاصله از هم جدا می‌شوند. یک فاصله درون یک گزینه می‌تواند با استفاده از اسکیپ نوشته شود.
•
enabled=<value> - مقدار <value> مشخص می‌کند که اقدام چه زمانی فعال است (در نسخه 0.3.0 اضافه شد)
  • 1 - اقدام همیشه فعال است
  • host-only - اقدام فقط برای عملیات بر روی میزبان فعال است
  • installroot-only - اقدام فقط برای عملیات در «installroot» جایگزین فعال است
•
mode=<value> - مقدار <value> حالت ارتباطی افزونه اقدامات را مشخص می‌کند (در نسخه 1.2.0 اضافه شد)
•
•
•
raise_error=<value> - مقدار <value> نحوه رسیدگی به خطاهای فرآیند اقدام را مشخص می‌کند. اینکه چه رخ می‌دهد اگر فرآیند اقدام شروع نشود، با کد خروج غیرصفر پایان یابد، به طور غیرعادی پایان یابد (سیگنال دریافت کند)، یا خطایی در حین ارتباط رخ دهد (خطای نحو، قطعی ارتباط، شکست در پردازش خط خروجی در حالت ارتباطی ساده). اگر این گزینه وجود نداشته باشد، برای سازگاری با گذشته raise_error=0 در نظر گرفته می‌شود (در نسخه 1.4.0 اضافه شد).
  • 0 - خطاها در لاگ ثبت می‌شوند
  • 1 - یک استثنا ایجاد می‌شود
هر فایل اجرایی به همراه آرگومان‌ها.

آرگومان‌ها با فاصله از هم جدا می‌شوند. یک فاصله درون یک آرگومان می‌تواند با استفاده از اسکیپ نوشته شود. اسکیپ کردن همچنین می‌تواند برای جلوگیری از جایگزینی و ارسال کاراکترهای خاص استفاده شود: \a، \b، \f، \n، \r، \t، \v. برداشتن اسکیپ آرگومان‌ها پس از جایگزینی انجام می‌شود.

متغیرهای زیر در دستور جایگزین خواهند شد:

  • ${pid} - شناسه فرآیند
  • ${plugin.version} - نسخه افزونه اقدامات (در نسخه 0.3.0 اضافه شد)
  • ${conf.<option_name>} - گزینه از پیکربندی پایه
  • ${conf.<repoid_pattern>.<option_name>[=<value_pattern>]} - فهرستی از جفت‌های «repoid.option=value» (در نسخه 1.1.0 اضافه شد)
  • ${var.<variable_name>} - متغیر
  • ${tmp.<actions_plugin_variable_name>} - متغیری که فقط در زمینه افزونه اقدامات وجود دارد
  • ${pkg.<package_attribute_name>} - مقدار صفت بسته
  • ${pkg.name} - نام بسته
  • ${pkg.arch} - معماری بسته
  • ${pkg.version} - نسخه بسته
  • ${pkg.release} - انتشار بسته
  • ${pkg.epoch} - مبدا زمانی (epoch) بسته
  • ${pkg.na} - نام.معماری بسته
  • ${pkg.evr} - مبدا زمانی-نسخه-انتشار بسته
  • ${pkg.nevra} - مقدار nevra بسته (مبدا زمانی 0 پنهان است)
  • ${pkg.full_nevra} - مقدار کامل nevra بسته (مبدا زمانی همیشه وجود دارد) name-epoch:version-release.arch
  • ${pkg.repo_id} - شناسه مخزن بسته
  • ${pkg.license} - مجوز بسته
  • ${pkg.location} - مسیر/موقعیت نسبی بسته از repodata
  • ${pkg.vendor} - ارائه‌دهنده بسته
  • ${pkg.action} - اقدام انجام‌شده بر روی بسته:
  • I - بسته تازه نصب‌شده
  • U - بسته نصب‌شده به عنوان ارتقا
  • D - بسته نصب‌شده به عنوان تنزل
  • R - بسته استفاده‌شده برای نصب مجدد
  • E - بسته پاک‌شده (حذف‌شده) از سیستم
  • O - بسته جایگزین‌شده (منسوخ‌شده/ارتقایافته/تنزل‌یافته/مجدداً نصب‌شده/حذف‌شده)
  • ? - بسته با تغییر دلیل نصب

دستور به ازای هر بسته‌ای که با package_filter و direction مطابقت داشته باشد ارزیابی خواهد شد. با این حال، پس از جایگزینی متغیرها، هرگونه دستور تکراری حذف می‌شود و هر دستور فقط یک بار در هر تراکنش اجرا خواهد شد. دستورات به صورت متوالی اجرا می‌شوند. هیچ موازی‌سازی وجود ندارد. جایگزینی آرگومان‌ها پس از تکمیل دستور قبلی انجام می‌شود. این ویژگی به جایگزینی اجازه می‌دهد از نتایج دستورات قبلی استفاده کند. ترتیب اجرای دستورات از ترتیب موجود در فایل‌های اقدامات پیروی می‌کند، اما ممکن است با ترتیب بسته‌ها در تراکنش متفاوت باشد. به عبارت دیگر، هنگامی که چند خط اقدام برای یک package_filter و direction یکسان تعریف می‌کنید، این خطوط در زمانی که package_filter و direction با بسته‌ای مطابقت یابد، به ترتیبی که در فایل اقدام تعریف شده‌اند اجرا خواهند شد. با این حال، زمان فراخوانی یک package_filter مشخص به موقعیت بسته مربوطه در تراکنش بستگی دارد.

جفت‌های repoid.option=value در فهرست با کاراکتر «,» از هم جدا می‌شوند. کاراکتر «,» درون مقدار با توالی اسکیپ "\x2C" جایگزین می‌شود. اگر از value_pattern استفاده شود، فقط جفت‌های دارای مقدار منطبق فهرست می‌شوند. repoid_pattern و value_pattern می‌توانند شامل الگوهای منطبق‌سازی (globs) باشند.

خروجی استاندارد هر اقدام (دستور) اجراشده دریافت و پردازش می‌شود. هر خط خروجی می‌تواند مقدار یک گزینه پیکربندی پایه، مقدار یک گزینه پیکربندی را در مخازن منطبق، یا یک متغیر را تغییر دهد. همچنین می‌تواند یک متغیر افزونه اقدامات را تنظیم یا لغو کند. مقدار این متغیر با استفاده از جایگزینی ${tmp.<actions_plugin_variable_name>} برای دستورات بعدی در دسترس خواهد بود.

اقدامات باید پیکربندی مخازن را در قلاب repos_configured تغییر دهند. در این مرحله، پیکربندی مخازن بارگذاری شده اما هنوز اعمال نشده است.

از نسخه 1.4.0، خط خروجی می‌تواند پیامی را در لاگر بنویسد، یک استثنای توقف یا یک استثنای خطا ایجاد کند.

  • tmp.<actions_plugin_variable_name>=<value> - مقدار متغیر افزونه اقدامات <actions_plugin_variable_name> را تنظیم می‌کند
  • tmp.<actions_plugin_variable_name> - در صورت وجود متغیر افزونه اقدامات، آن را حذف می‌کند
  • conf.<option_name>=<value> - مقدار گزینه <option_name> را در پیکربندی پایه تنظیم می‌کند
  • conf.<repoid_pattern>.<option_name>=<value> - مقدار گزینه <option_name> را در مخازن منطبق تنظیم می‌کند (در نسخه 1.1.0 اضافه شد)
  • var.<variable_name>=<value> - مقدار متغیر <variable_name> را تنظیم می‌کند
  • stop=<message> - یک استثنای توقف همراه با <message> ایجاد می‌کند (در نسخه 1.4.0 اضافه شد)
  • error=<message> - پیام خطای <message> در لاگ ثبت می‌شود یا در صورت raise_error=1 یک استثنای خطا همراه با <message> ایجاد می‌کند (در نسخه 1.4.0 اضافه شد)
  • log.<level>=<message> - پیام <message> را با اولویت <level> در لاگر می‌نویسد (در نسخه 1.4.0 اضافه شد)
سطوح: CRITICAL، ERROR، WARNING، NOTICE، INFO، DEBUG، TRACE

حالت ارتباطی «json» یک کانال ارتباطی دوطرفه بین افزونه اقدامات و فرآیند با استفاده از مدل درخواست-پاسخ برقرار می‌کند. فرآیند درخواست‌ها را در خروجی استاندارد می‌نویسد و پاسخ‌های افزونه اقدامات را از ورودی استاندارد می‌خواند. تمامی ارتباطات در قالب JSON مدیریت می‌شوند.

قالب پیام درخواست از فرآیند:

{"op":"<operation>", "domain":"<domain>", "args":{}}

قالب پاسخ:

{"op":"reply", "requested_op":"<operation_from_request>", "domain":"<domain_from_request>",
  "status":"OK", "return":{}}

قالب پاسخ همراه با پیام خطا:

{"op":"reply", "requested_op":"<operation_from_request>", "domain":"<domain_from_request>",
  "status":"ERROR", "message":"<error message>"}

  • get - درخواست برای دریافت مقادیر
  • set - درخواست برای تنظیم یک مقدار
  • new - ایجاد یک پیکربندی مخزن جدید
  • log - نوشتن یک پیام در لاگر (در نسخه 1.4.0 اضافه شد)
  • stop - ایجاد یک استثنای توقف همراه با پیام (در نسخه 1.4.0 اضافه شد)
  • error - پیام خطا در لاگ ثبت می‌شود یا در صورت raise_error=1 یک استثنای خطا همراه با پیام ایجاد می‌کند (در نسخه 1.4.0 اضافه شد)

عملیات get برای چند <domain> تعریف شده است.

  • conf - درخواست خواندن مقدار یک پیکربندی (پیکربندی سراسری یا مخزن)
  • vars - درخواست خواندن مقدار متغیرها
  • actions_vars - درخواست خواندن مقدار متغیرهای افزونه اقدامات - این متغیرها فقط در زمینه افزونه اقدامات وجود دارند
  • actions_attrs - امکان دریافت شناسه فرآیند و نسخه افزونه اقدامات را فراهم می‌کند
  • packages - درخواست فهرست کردن بسته‌های موجود و نصب‌شده
  • trans_packages - درخواست فهرست کردن بسته‌ها در تراکنش
  • cmdline_packages_paths - درخواست فهرست کردن بسته‌های مشخص‌شده در خط فرمان

قالب درخواست:

{"op":"get", "domain":"conf", "args":{"key":"<name>"}}
{"op":"get", "domain":"conf", "args":{"key":"<repo_id>.<name>"}}

قالب پاسخ:

{"op":"reply", "requested_op":"get", "domain":"conf", "status":"OK",
  "return":{"keys_val":[{"key":"<name>", "value":"<value>"}]}}
{"op":"reply", "requested_op":"get", "domain":"conf", "status":"OK",
  "return":{"keys_val":[{"key":"<repo_id>.<name>", "value":"<value>"}]}}
{"op":"reply", "requested_op":"get", "domain":"conf", "status":"ERROR",
  "message":"<error message>"}

توضیحات:

  • <name> - نام یک گزینه پیکربندی سراسری یا در صورت مشخص بودن <repo_id>، گزینه پیکربندی مخزن
  • <repo_id> - شناسه مخزن؛ در یک درخواست می‌تواند شامل الگوهای تطبیق (globs) باشد که در این صورت مقدار گزینه پیکربندی برای تمامی مخازن منطبق خوانده می‌شود
  • <value> - مقدار خوانده‌شده گزینه پیکربندی
  • <error message> - پیام خطا

هنگام استفاده از <repo_id>، تعداد موارد keys_val در پاسخ به تعداد مخازن منطبق بستگی دارد.

مثال:

{"op":"get", "domain":"conf", "args":{"key":"countme"}}
{"op":"reply", "requested_op":"get", "domain":"conf", "status":"OK",
  "return":{"keys_val":[{"key":"countme", "value":"0"}]}}
{"op": "get", "domain": "conf", "args": {"key": "*.enabled"}}
{"op": "reply", "requested_op": "get", "domain": "conf", "status": "OK",
  "return": {
    "keys_val": [{"key": "dnf-ci-fedora.enabled", "value": "1"},
                 {"key": "dnf-ci-fedora-updates.enabled", "value": "1"},
                 {"key": "dnf-ci-thirdparty.enabled", "value": "0"},
                 {"key": "test-repo.enabled", "value": "0"}]}}

قالب درخواست:

{"op":"get", "domain":"vars", "args":{"name":"<name>"}}

قالب پاسخ:

{"op":"reply", "requested_op":"get", "domain":"vars", "status":"OK",
  "return":{"vars":[{"name":"<name>", "value":"<value>"}]}}

توضیحات:

  • <name> - نام متغیر؛ در یک درخواست می‌تواند شامل الگوهای تطبیق (globs) باشد که در این صورت مقدار تمامی متغیرهای منطبق خوانده خواهد شد
  • <value> - مقدار خوانده‌شده متغیر

تعداد موارد vars در پاسخ به تعداد متغیرهای منطبق بستگی دارد.

مثال:

{"op":"get", "domain":"vars", "args":{"name":"test_var*"}}
{"op":"reply", "requested_op":"get", "domain":"vars", "status":"OK",
  "return":{"vars":[{"name":"test_var1", "value":"value1"}]}}
{"op":"get", "domain":"vars", "args":{"name":"nonexist_var"}}
{"op":"reply", "requested_op":"get", "domain":"vars", "status":"OK",
  "return":{"vars":[]}}

قالب درخواست:

{"op":"get", "domain":"actions_vars", "args":{"name":"<name>"}}

قالب پاسخ:

{"op":"reply", "requested_op":"get", "domain":"actions_vars", "status":"OK",
  "return":{"actions_vars":[{"name":"<name>", "value":"<value>"}]}}

توضیحات:

  • <name> - نام متغیر اقدام؛ در یک درخواست می‌تواند شامل الگوهای تطبیق (globs) باشد که در این صورت مقدار تمامی متغیرهای اقدام منطبق خوانده خواهد شد
  • <value> - مقدار خوانده‌شده متغیر اقدام

تعداد موارد actions_vars در پاسخ به تعداد متغیرهای اقدام منطبق بستگی دارد.

مثال:

{"op":"get", "domain":"actions_vars", "args":{"name":"test_actions_var*"}}
{"op":"reply", "requested_op":"get", "domain":"actions_vars", "status":"OK",
  "return":{"actions_vars":[{"name":"test_actions_var1", "value":"value1"}]}}
{"op":"get", "domain":"actions_vars", "args":{"name":"nonexist_var"}}
{"op":"reply", "requested_op":"get", "domain":"actions_vars", "status":"OK",
  "return":{"actions_vars":[]}}

قالب درخواست:

{"op":"get", "domain":"actions_attrs", "args":{"key":"<name>"}}

قالب پاسخ:

{"op":"reply", "requested_op":"get", "domain":"actions_attrs", "status":"OK",
  "return":{"actions_attrs":[{"key":"<name>", "value":"<value>"}]}}

توضیحات:

•
<name> - نام صفت اقدام؛ در یک درخواست می‌تواند شامل الگوهای تطبیق (globs) باشد که در این صورت مقدار تمام صفت‌های منطبق افزونه اقدامات خوانده خواهد شد. در حال حاضر از دو صفت پشتیبانی می‌شود: pid و version.
  • pid - شناسه فرآیند افزونه اقدامات
  • version - نسخه افزونه اقدامات، رشته‌ای در قالب MAJOR.MINOR.MICRO
•
<value> - مقدار خوانده‌شده صفت اقدام

تعداد موارد actions_attrs در پاسخ به تعداد صفت‌های اقدام منطبق بستگی دارد.

مثال:

{"op":"get", "domain":"actions_attrs", "args":{"key":"*"}}
{"op":"reply", "requested_op":"get", "domain":"actions_attrs", "status":"OK",
  "return":{
    "actions_attrs":[{"key":"pid", "value":"523"},
                     {"key":"version", "value":"1.4.0"}]}}
{"op":"get", "domain":"actions_attrs", "args":{"key":"nonexist_attribute"}}
{"op":"reply", "requested_op":"get", "domain":"actions_attrs", "status":"OK",
  "return":{"actions_attrs":[]}}

دامنه packages برای دریافت بسته‌های موجود و نصب‌شده استفاده می‌شود. دامنه trans_packages برای دریافت بسته‌های درون تراکنش استفاده می‌شود. دامنه trans_packages فقط در بازخوانی‌های goal_resolved، pre_transaction و post_transaction قابل استفاده است.

قالب درخواست:

{"op":"get", "domain":"packages", "args":{"output":["<pkg_attr>"]}}
{"op":"get", "domain":"packages", "args":{"output":["<pkg_attr>"],
  "params":[{"key":"<param_name>"}]}}
{"op":"get", "domain":"packages", "args":{"output":["<pkg_attr>"],
  "filters":[{"key":"<filter_name>", "value":"<value>", "operator":"<cmp_operator>"}]}}
{"op":"get", "domain":"packages", "args":{"output":["<pkg_attr>"],
  "params":[{"key":"<param_name>"}],
  "filters":[{"key":"<filter_name>", "value":"<value>", "operator":"<cmp_operator>"}]}}
{"op":"get", "domain":"trans_packages", "args":{"output":["<pkg_attr>"]}}
{"op":"get", "domain":"trans_packages", "args":{"output":["<pkg_attr>"],
  "params":[{"key":"<param_name>"}]}}
{"op":"get", "domain":"trans_packages", "args":{"output":["<pkg_attr>"],
  "filters":[{"key":"<filter_name>", "value":"<value>", "operator":"<cmp_operator>"}]}}
{"op":"get", "domain":"trans_packages", "args":{"output":["<pkg_attr>"],
  "params":[{"key":"<param_name>"}],
  "filters":[{"key":"<filter_name>", "value":"<value>", "operator":"<cmp_operator>"}]}}

قالب پاسخ:

{"op":"reply", "requested_op":"get", "domain":"packages", "status":"OK",
  "return":{"packages":[{"<pkg_attr>":"<attr_value>"}]}}
{"op":"reply", "requested_op":"get", "domain":"trans_packages", "status":"OK",
  "return":{"trans_packages":[{"<pkg_attr>":"<attr_value>"}]}}
{"op":"reply", "requested_op":"get", "domain":"packages", "status":"ERROR",
  "message":"<error message>"}
{"op":"reply", "requested_op":"get", "domain":"trans_packages", "status":"ERROR",
  "message":"<error message>"}

توضیحات:

•
<pkg_attr> - صفت بسته برای بازگرداندن؛ آرایه می‌تواند شامل چند صفت باشد

صفات عمومی

  • name - نام بسته
  • arch - معماری بسته
  • version - نسخه بسته
  • release - انتشار بسته
  • epoch - مبدا زمانی بسته
  • na - نام.معماری بسته
  • evr - مبدا زمانی-نسخه-انتشار بسته
  • nevra - مقدار nevra بسته (مبدا زمانی 0 پنهان است)
  • full_nevra - مقدار کامل nevra بسته (مبدا زمانی همیشه وجود دارد) name-epoch:version-release.arch
  • download_size - حجم دانلود فایل بسته
  • install_size - اندازه‌ای که بسته پس از نصب بر روی دیسک اشغال می‌کند
  • repo_id - شناسه مخزن بسته
  • license - مجوز بسته
  • location - مسیر/موقعیت نسبی بسته از repodata
  • vendor - ارائه‌دهنده بسته

صفات قابل استفاده فقط با دامنه trans_packages

•
action - اقدام انجام‌شده بر روی بسته
  • I - بسته جدیداً نصب‌شده
  • U - بسته نصب‌شده به عنوان ارتقا
  • D - بسته نصب‌شده به عنوان تنزل
  • R - بسته استفاده‌شده برای نصب مجدد
  • E - بسته پاک‌شده (حذف‌شده) از سیستم
  • O - بسته جایگزین‌شده (منسوخ‌شده/ارتقایافته/تنزل‌یافته/مجدداً نصب‌شده/حذف‌شده)
  • ? - بسته با تغییر دلیل نصب
•
direction - جهت بسته در تراکنش
  • IN - بسته‌های ورودی به سیستم (تنزل، نصب، نصب مجدد، ارتقا)
  • OUT - بسته‌های خروجی از سیستم (ارتقایافته، تنزل‌یافته، مجدداً نصب‌شده، حذف‌شده، جایگزین/منسوخ‌شده)
  • <param_name> - یکی از موارد IGNORE_EXCLUDES، IGNORE_MODULAR_EXCLUDES، IGNORE_REGULAR_EXCLUDES، IGNORE_REGULAR_CONFIG_EXCLUDES، IGNORE_REGULAR_USER_EXCLUDES
  • <filter_name> - نام صفت بسته برای پالایش؛ آرایه می‌تواند شامل چند صفت باشد

    صفات عمومی

  • name - پالایش بسته‌ها بر اساس نام، از <value> و <cmp_operator> استفاده می‌کند
  • arch - پالایش بسته‌ها بر اساس معماری، از <value> و <cmp_operator> استفاده می‌کند
  • version - پالایش بسته‌ها بر اساس نسخه، از <value> و <cmp_operator> استفاده می‌کند
  • release - پالایش بسته‌ها بر اساس انتشار، از <value> و <cmp_operator> استفاده می‌کند
  • epoch - پالایش بسته‌ها بر اساس مبدا زمانی، از <value> و <cmp_operator> استفاده می‌کند
  • nevra - پالایش بسته‌ها بر اساس nevra (مبدا زمانی 0 پنهان است)، از <value> و <cmp_operator> استفاده می‌کند
  • repo_id - پالایش بسته‌ها بر اساس شناسه مخزن، از <value> و <cmp_operator> استفاده می‌کند
  • available - پالایش بسته‌های موجود
  • installed - پالایش بسته‌های نصب‌شده
  • userinstalled - پالایش بسته‌های نصب‌شده توسط کاربر
  • installonly - پالایش بسته‌های فقط‌نصب (installonly)
  • description - پالایش بسته‌ها بر اساس توضیحات، از <value> و <cmp_operator> استفاده می‌کند
  • file - پالایش بسته‌ها بر اساس فایل‌های درون آن‌ها، از <value> و <cmp_operator> استفاده می‌کند
  • upgradable - پالایش بسته‌های نصب‌شده‌ای که ارتقا برای آن‌ها موجود است
  • upgrades - پالایش بسته‌های موجودی که ارتقای بسته‌های نصب‌شده هستند
  • downgradable - پالایش بسته‌های نصب‌شده‌ای که تنزل برای آن‌ها موجود است
  • downgrades - پالایش بسته‌های موجودی که تنزل بسته‌های نصب‌شده هستند

صفات قابل استفاده فقط با دامنه trans_packages

•
direction - بسته‌ها را بر اساس جهت آن‌ها در یک تراکنش پالایش می‌کند، از <value> استفاده می‌کند؛ مقادیر پشتیبانی‌شده:
  • IN - بسته‌های ورودی به سیستم (تنزل، نصب، نصب مجدد، ارتقا)
  • OUT - بسته‌های خروجی از سیستم (ارتقایافته، تنزل‌یافته، مجدداً نصب‌شده، حذف‌شده، جایگزین/منسوخ‌شده)
  • <value> - مقداری که توسط برخی فیلترها استفاده می‌شود؛ نوع مقایسه به <cmp_operator> بستگی دارد
  • <cmp_operator> - عملگر مورد استفاده توسط فیلتر برای ارزیابی تطابق با <value>؛ در صورت عدم تعیین، EQ در نظر گرفته می‌شود
  • <attr_value> - مقدار صفت بسته
  • <error message> - پیام خطا

تعداد موارد packages و trans_packages در پاسخ به تعداد بسته‌های منطبق بستگی دارد.

مثال:

{"op":"get", "domain":"packages",
  "args":{
    "params":[{"key":"IGNORE_EXCLUDES"}],
    "filters":[{"key":"name", "value":"lame*", "operator":"GLOB"}],
    "output":["nevra"]}}
{"op":"reply", "requested_op":"get", "domain":"packages", "status":"OK", "return":{"packages":[
  { "nevra":"lame-3.100-5.fc29.src" }, { "nevra":"lame-3.100-5.fc29.x86_64" },
  { "nevra":"lame-libs-3.100-5.fc29.x86_64" }, { "nevra":"lame-3.100-4.fc29.src" },
  { "nevra":"lame-3.100-4.fc29.x86_64" }, { "nevra":"lame-libs-3.100-4.fc29.x86_64"}]}}
{"op":"get", "domain":"packages",
  "args":{
    "params":[{"key":"UNKNOWN"}],
    "filters":[{"key":"name", "value":"lame*", "operator":"GLOB"}],
    "output":["nevra"]}}
{"op":"reply", "requested_op":"get", "domain":"packages", "status":"ERROR",
  "message":"Bad key \"UNKNOWN\" for params"}
{"op":"get", "domain":"trans_packages",
  "args":{
    "filters":[{"key":"direction", "value":"IN"}, {"key":"arch", "value":"x86_64"}],
    "output":["action", "name", "version", "repo_id"]}}
{"op":"reply", "requested_op":"get", "domain":"trans_packages", "status":"OK",
  "return":{
    "trans_packages":[
      {"action":"I", "name":"glibc", "version":"2.28", "repo_id":"dnf-ci-fedora-updates"},
      {"action":"I", "name":"glibc-all-langpacks", "version":"2.28", "repo_id":"dnf-ci-fedora-updates"},
      {"action":"I", "name":"glibc-common", "version":"2.28", "repo_id":"dnf-ci-fedora-updates"},
      {"action":"I", "name":"filesystem", "version":"3.9", "repo_id":"dnf-ci-fedora"}]}}

قالب درخواست:

{"op":"get", "domain":"cmdline_packages_paths", "args":{}}
{"op":"get", "domain":"cmdline_packages_paths", "args":{
  "filters":[{"key":"path", "value":"<value>"}]}}
{"op":"get", "domain":"cmdline_packages_paths", "args":{
  "filters":[{"key":"path", "value":"<value>", "operator":"<cmp_operator>"}]}}

قالب پاسخ:

{"op":"reply", "requested_op":"get", "domain":"cmdline_packages_paths", "status":"OK",
  "return":{"cmdline_packages_paths":["<pkg_path>"]}}

توضیحات:

  • <value> - در صورت تعیین، فقط مسیرهای منطبق بر الگوی ارائه‌شده را برمی‌گرداند؛ نوع مقایسه به <cmp_operator> بستگی دارد
  • <cmp_operator> - عملگر ارزیابی اینکه آیا مسیر با الگوی درون <value> مطابقت دارد یا خیر؛ در صورت عدم تعیین، EQ در نظر گرفته می‌شود
  • <pkg_path> - مسیر بسته مشخص‌شده در خط فرمان

تعداد موارد cmdline_packages_paths در پاسخ به تعداد مسیرهای بسته‌های منطبق در خط فرمان بستگی دارد.

مثال:

{"op":"get", "domain":"cmdline_packages_paths",
  "args":{"filters":[{"key":"path", "value":"/local/*", "operator":"GLOB"}]}}
{"op":"reply", "requested_op":"get", "domain":"cmdline_packages_paths", "status":"OK",
  "return":{"cmdline_packages_paths":["/local/packageB.rpm", "/local/packageC.rpm"]}}

برخی از عملیات get از <cmp_operator> پشتیبانی می‌کنند. افزونه اقدامات از عملگرهای مقایسه‌ای زیر پشتیبانی می‌کند:

  • EQ - برابری دقیق آرگومان‌ها
  • IEQ - برابری رشته‌ای، مقایسه غیرحساس به حروف بزرگ و کوچک
  • GT - بزرگ‌تر از
  • GTE - بزرگ‌تر یا مساوی
  • LT - کوچک‌تر از
  • LTE - کوچک‌تر یا مساوی
  • CONTAINS - شامل یک زیررشته بودن
  • ICONTAINS - شامل یک زیررشته بودن، جستجوی غیرحساس به حروف بزرگ و کوچک
  • STARTSWITH - شروع شدن با یک زیررشته
  • ISTARTSWITH - شروع شدن با یک زیررشته، مقایسه غیرحساس به حروف بزرگ و کوچک
  • ENDSWITH - پایان یافتن با یک زیررشته
  • IENDSWITH - پایان یافتن با یک زیررشته، مقایسه غیرحساس به حروف بزرگ و کوچک
  • REGEX - تطابق با یک عبارت باقاعده
  • IREGEX - تطابق با یک عبارت باقاعده، ارزیابی غیرحساس به حروف بزرگ و کوچک
  • GLOB - تطابق با یک الگوی glob
  • IGLOB - تطابق با یک الگوی glob، ارزیابی غیرحساس به حروف بزرگ و کوچک

مفهوم هر عملگر را می‌توان با استفاده از پیشوند NOT_ معکوس کرد. مثال‌ها: NOT_EQ، NOT_GT.

عملیات set برای چند <domain> تعریف شده است.

  • conf - درخواست برای تنظیم یک مقدار پیکربندی (پیکربندی سراسری یا مخزن)
  • vars - درخواست برای تنظیم مقدار یک متغیر
  • actions_vars - درخواست برای تنظیم یک متغیر افزونه اقدامات - این متغیرها فقط در زمینه افزونه اقدامات وجود دارند

قالب درخواست:

{"op":"set", "domain":"conf", "args":{"key":"<name>", "value":"<value>"}}
{"op":"set", "domain":"conf", "args":{"key":"<repo_id>.<name>", "value":"<value>"}}

قالب پاسخ:

{"op":"reply", "requested_op":"set", "domain":"conf", "status":"OK",
  "return":{"keys_val":[{"key":"<name>", "value":"<value>"}]}}
{"op":"reply", "requested_op":"set", "domain":"conf", "status":"OK",
  "return":{"keys_val":[{"key":"<repo_id>.<name>", "value":"<value>"}]}}
{"op":"reply", "requested_op":"set", "domain":"conf", "status":"ERROR",
  "message":"<error message>"}

توضیحات:

  • <name> - نام یک گزینه پیکربندی سراسری یا در صورت مشخص بودن <repo_id>، گزینه پیکربندی مخزن
  • <repo_id> - شناسه مخزن؛ در یک درخواست می‌تواند شامل الگوهای تطبیق (globs) باشد که در این صورت مقدار گزینه پیکربندی برای تمامی مخازن منطبق تنظیم می‌شود
  • <value> - در درخواست، مقداری که باید تنظیم شود؛ در پاسخ، مقدار واقعی پس از تنظیم
  • <error message> - پیام خطا

هنگام استفاده از <repo_id>، تعداد موارد keys_val در پاسخ به تعداد مخازن منطبق بستگی دارد.

مثال:

{"op":"set", "domain":"conf", "args":{"key":"countme", "value":"1"}}
{"op":"reply", "requested_op":"set", "domain":"conf", "status":"OK",
  "return":{"keys_val":[{"key":"countme", "value":"1"}]}}
{"op":"set", "domain":"conf", "args":{"key":"dnf-ci-fedora*.enabled", "value":"1"}}
{"op":"reply", "requested_op":"set", "domain":"conf", "status":"OK",
  "return":{
    "keys_val":[{"key":"dnf-ci-fedora.enabled", "value":"1"},
                {"key":"dnf-ci-fedora-updates.enabled", "value":"1"}]}}

قالب درخواست:

{"op":"set", "domain":"vars", "args":{"name":"<name>", "value":"<value>"}}
{"op":"set", "domain":"vars", "args":{"name":"<name>"}}

قالب پاسخ:

{"op":"reply", "requested_op":"set", "domain":"vars", "status":"OK",
  "return":{"vars":[{"name":"<name>", "value":"<value>"}]}}
{"op":"reply", "requested_op":"set", "domain":"vars", "status":"OK",
  "return":{"vars":[{"name":"<name>"}]}}
{"op":"reply", "requested_op":"set", "domain":"vars", "status":"ERROR",
  "message":"<error message>"}

توضیحات:

  • <name> - نام متغیر
  • <value> - در درخواست، مقداری که باید تنظیم شود؛ در صورت عدم تعیین، به این معنی است که متغیر باید حذف شود. در پاسخ، مقدار واقعی پس از تنظیم؛ در صورت عدم تعیین، متغیر وجود نداشته یا حذف شده است
  • <error message> - پیام خطا

مثال:

{"op":"set", "domain":"vars", "args":{"name":"test_var1", "value":"value1"}}
{"op":"reply", "requested_op":"set", "domain":"vars", "status":"OK",
  "return":{"vars":[{"name":"test_var1", "value":"value1"}]}}

قالب درخواست:

{"op":"set", "domain":"actions_vars", "args":{"name":"<name>", "value":"<value>"}}
{"op":"set", "domain":"actions_vars", "args":{"name":"<name>"}}

قالب پاسخ:

{"op":"reply", "requested_op":"set", "domain":"actions_vars", "status":"OK",
  "return":{"vars":[{"name":"<name>", "value":"<value>"}]}}
{"op":"reply", "requested_op":"set", "domain":"actions_vars", "status":"OK",
  "return":{"vars":[{"name":"<name>"}]}}
{"op":"reply", "requested_op":"set", "domain":"actions_vars", "status":"ERROR",
  "message":"<error message>"}

توضیحات:

  • <name> - نام متغیر اقدام
  • <value> - در درخواست، مقداری که باید تنظیم شود؛ در صورت عدم تعیین، به این معنی است که متغیر باید حذف شود. در پاسخ، مقدار واقعی پس از تنظیم؛ در صورت عدم تعیین، متغیر وجود نداشته یا حذف شده است
  • <error message> - پیام خطا

مثال:

{"op":"set", "domain":"actions_vars", "args":{"name":"test_actions_var1", "value":"value1"}}
{"op":"reply", "requested_op":"set", "domain":"actions_vars", "status":"OK",
  "return":{"actions_vars":[{"name":"test_actions_var1", "value":"value1"}]}}

عملیات new یک پیکربندی مخزن جدید ایجاد می‌کند. این عملیات فقط در بازخوانی repos_configured قابل استفاده است.

قالب درخواست:

{"op":"new", "domain":"repoconf",
  "args":{"keys_val":[{"key":"repo_id", "value":"<repo_id>"},
                      {"key":"<repo_opt>", "value":"<opt_value>"}]}

قالب پاسخ:

{"op":"reply", "requested_op":"new", "domain":"repoconf", "status":"OK",
  "return":{"keys_val":[{"key":"repo_id", "value":"<repo_id>"},
                        {"key":"<repo_opt>", "value":"<opt_value>"}]}}
{"op":"reply", "requested_op":"new", "domain":"repoconf", "status":"ERROR",
  "message":"<error_message>"}

توضیحات:

  • <repo_id> - شناسه مخزن
  • <repo_opt> - هر گزینه پیکربندی موجود برای مخزن
  • <opt_value> - مقداری که باید برای گزینه پیکربندی تنظیم شود

فیلد keys_val باید حداقل شامل یک عنصر باشد - تعیین repo_id الزامی است. تنظیم سایر گزینه‌های پیکربندی مخزن اختیاری است. اگر گزینه enabled وجود نداشته باشد، مخزن به صورت پیش‌فرض غیرفعال است. پاسخ شامل همان کلیدهای درخواست و مقادیر واقعی آن‌ها خواهد بود.

مثال:

{"op":"new", "domain":"repoconf",
  "args":{
    "keys_val":[{"key":"repo_id", "value":"test-repo"},
                {"key":"name", "value":"Test repository"},
                {"key":"enabled", "value":"false"},
                {"key":"baseurl", "value":"https://xyz.com/rpm"}]}}
{"op":"reply", "requested_op":"new", "domain":"repoconf", "status":"OK",
  "return":{
    "keys_val":[{"key":"repo_id", "value":"test-repo"},
                {"key":"name", "value":"Test repository"},
                {"key":"enabled", "value":"0"},
                {"key":"baseurl", "value":"https://xyz.com/rpm"}]}}

عملیات log پیامی را در لاگر می‌نویسد.

قالب درخواست:

{"op":"log", "args":{"level":"<level>", "message":"<message>"}}

قالب پاسخ:

{"op":"reply", "requested_op":"log", "domain":"log", "status":"OK"}
{"op":"reply", "requested_op":"log", "domain":"log", "status":"ERROR",
  "message":"Unknown log level '<level_from_request>'"}

توضیحات:

  • <level> - مقادیر CRITICAL، ERROR، WARNING، NOTICE، INFO، DEBUG، TRACE
  • <message> - متنی که باید در لاگ نوشته شود
  • <level_from_request> - سطح ارائه‌شده در درخواست، در صورتی که حاوی مقداری پشتیبانی‌نشده باشد

مثال:

{"op":"log", "args":{"level":"WARNING", "message":"My warning message"}}
{"op":"reply", "requested_op":"log", "domain":"log", "status":"OK"}

عملیات stop یک استثنای توقف همراه با یک پیام ایجاد می‌کند.

قالب درخواست:

{"op":"stop", "args":{"message":"<message>"}}

توضیحات:

•
<message> - متنی که باید در استثنای توقف گنجانده شود

پس از این درخواست، انتظار می‌رود که برنامه خاتمه یابد. افزونه اقدامات پاسخی ارسال نمی‌کند بلکه کانال ارتباطی را می‌بندد - لوله‌های متصل به خروجی و ورودی استاندارد فرآیند.

مثال:

{"op":"stop", "args":{"message":"I want to stop the task"}}

عملیات error پیام خطا را در لاگ ثبت می‌کند یا در صورت raise_error=1 یک استثنای خطا همراه با پیام ایجاد می‌نماید.

قالب درخواست:

{"op":"error", "args":{"message":"<message>"}}

قالب پاسخ:

{"op":"reply", "requested_op":"error", "domain":"error", "status":"OK"}

توضیحات:

•
<message> - متنی که در لاگ نوشته می‌شود یا در صورت raise_error=1 در استثنای خطا گنجانده می‌شود

اگر raise_error=1 باشد، انتظار می‌رود که برنامه خاتمه یابد. افزونه اقدامات پاسخی ارسال نمی‌کند بلکه کانال ارتباطی را می‌بندد - لوله‌های متصل به خروجی و ورودی استاندارد فرآیند.

مثال:

{"op":"error", "args":{"message":"Error in action process 1"}}
{"op":"reply", "requested_op":"error", "domain":"error", "status":"OK"}

# سربرگ را با شناسه فرآیند چاپ می‌کند
pre_base_setup::::/usr/bin/sh -c echo\ -------------------------------------\ >>/tmp/actions-trans.log
pre_base_setup::::/usr/bin/sh -c date\ >>/tmp/actions-trans.log
pre_base_setup::::/usr/bin/sh -c echo\ libdnf5\ pre_base_setup\ was\ called.\ Process\ ID\ =\ '${pid}'.\ >>/tmp/actions-trans.log
pre_base_setup:::enabled=installroot-only:/usr/bin/sh -c echo\ run\ in\ alternative\ "installroot":\ installroot\ =\ '${conf.installroot}'\ >>/tmp/actions-trans.log
# مقدار گزینه پیکربندی «defaultyes» را چاپ می‌کند.
pre_base_setup::::/usr/bin/sh -c echo\ pre_base_setup:\ conf.defaultyes=${conf.defaultyes}\ >>/tmp/actions.log
# پیامی مبنی بر فراخوانی بازخوانی «post_base_setup» چاپ می‌کند.
post_base_setup::::/usr/bin/sh -c echo\ libdnf5\ post_base_setup\ was\ called.\ >>/tmp/actions-trans.log
# برنامه «add_new_repo» را با ارتباط json اجرا می‌کند.
# این برنامه برای مثال می‌تواند پیکربندی‌های جدیدی برای مخازن اضافه کند.
repos_configured:::mode=json:/usr/local/bin/add_new_repo
# فهرستی از مخازن پیکربندی‌شده را به همراه وضعیت فعال بودن آن‌ها چاپ می‌کند.
repos_configured::::/usr/bin/sh -c echo\ Repositories:\ ${conf.*.enabled}\ >>/tmp/repos.log
# فهرستی از مخازنی که از پروتکل http در baseurl استفاده می‌کنند را چاپ می‌کند.
repos_configured::::/usr/bin/sh -c echo\ "${conf.*.baseurl=*http://*}"\ >>/tmp/baseurl_http.log
# تمام مخازنی که شناسه آن‌ها با «rpmfusion» شروع می‌شود را غیرفعال می‌کند.
repos_configured::::/usr/bin/sh -c echo\ conf.rpmfusion*.enabled=0
# برنامه «check_transaction» را با ارتباط json اجرا می‌کند و در صورت بروز خطا در برنامه خاتمه می‌یابد.
# این برنامه برای مثال می‌تواند بسته‌های ممنوعه را در یک تراکنش بررسی کرده و یک پیام توقف ارسال کند.
pre_transaction:::mode=json raise_error=1:/usr/local/bin/check_transaction
# اطلاعات مربوط به شروع تراکنش را چاپ می‌کند.
# از آنجا که package_filter خالی است، دستورات را یک بار اجرا می‌کند.
pre_transaction::::/usr/bin/sh -c echo\ Transaction\ start.\ Packages\ in\ transaction:\ >>/tmp/actions-trans.log
# تمامی بسته‌ها (اقدام بسته، full_nevra، شناسه مخزن) در تراکنش را درون یک فایل لاگ می‌کند.
# از دستور پوسته «echo» و هدایت خروجی به فایل استفاده می‌کند.
pre_transaction:*:::/usr/bin/sh -c echo\ '${pkg.action}'\ '${pkg.full_nevra}'\ '${pkg.repo_id}'\ >>/tmp/actions-trans.log
# تاریخ و زمان و اطلاعات پایان تراکنش را چاپ می‌کند.
# از آنجا که package_filter خالی است، دستورات را یک بار اجرا می‌کند.
post_transaction::::/usr/bin/sh -c date\ >>/tmp/actions-trans.log
post_transaction::::/usr/bin/sh -c echo\ Transaction\ end.\ Repositories\ used\ in\ the\ transaction:\ >>/tmp/actions-trans.log
# تمامی مخازنی که بسته‌های آن‌ها در تراکنش برای نصب روی سیستم استفاده شده‌اند را در فایل لاگ ثبت می‌کند.
# هر مخزن فقط یک بار فهرست می‌شود، حتی اگر چندین بسته از همان مخزن استفاده شده باشد.
# همان دستور (پس از جایگزینی متغیرها) تنها یک بار در هر تراکنش اجرا می‌شود.
post_transaction:*:in::/usr/bin/sh -c echo\ '${pkg.repo_id}'\ >>/tmp/actions-trans.log
# ==============================================================================================
# دو اقدام بعدی افزونه snapper در DNF4 را شبیه‌سازی می‌کنند. این اقدامات از برنامه خط فرمان «snapper» استفاده می‌کنند.
# توضیحات اسنپ‌شات را ایجاد کرده و آن را در متغیر «tmp.snapper_descr» ذخیره می‌کند.
pre_transaction::::/usr/bin/sh -c echo\ "tmp.snapper_descr=$(ps\ -o\ command\ --no-headers\ -p\ '${pid}')"
# یک اسنپ‌شات pre قبل از تراکنش ایجاد کرده و شماره اسنپ‌شات را در متغیر «tmp.snapper_pre_number» ذخیره می‌کند.
pre_transaction::::/usr/bin/sh -c echo\ "tmp.snapper_pre_number=$(snapper\ create\ -t\ pre\ -p\ -d\ '${tmp.snapper_descr}')"
# اگر متغیر «tmp.snapper_pre_number» وجود داشته باشد، یک اسنپ‌شات post بعد از تراکنش ایجاد کرده و متغیرهای استفاده‌شده را حذف می‌کند.
post_transaction::::/usr/bin/sh -c [\ -n\ "${tmp.snapper_pre_number}"\ ]\ &&\ snapper\ create\ -t\ post\ --pre-number\ "${tmp.snapper_pre_number}"\ -d\ "${tmp.snapper_descr}"\ ;\ echo\ tmp.snapper_pre_number\ ;\ echo\ tmp.snapper_descr

فایل AUTHORS.md را در توزیع منبع dnf5 ببینید.

مشارکت‌کنندگان در پروژه dnf5.

September 6, 2026