.nh
.TH oci-hooks 5 OCI Hooks Configuration
W. Trevor King
MAY 2018

.SH "نام (NAME)"
oci-hooks \- دایرکتوری‌های پیکربندی قلاب‌های (hooks) مبتنی بر OCI


.SH "خلاصه دستور (SYNOPSIS)"
\fB/usr/share/containers/oci/hooks.d/*.json\fR


.SH "توضیحات (DESCRIPTION)"
روشی را برای کاربران فراهم می‌کند تا قلاب‌های مد نظر برای کانتینرهای «ابتکار کانتینر باز» (Open Container Initiative) را به گونه‌ای پیکربندی کنند که فقط برای کانتینرهایی که به عملکرد آن‌ها نیاز دارند و تنها در مراحلی که مورد نیاز هستند اجرا شوند.

.SH "دایرکتوری‌ها (DIRECTORIES)"
قلاب‌ها با استفاده از فایل‌های JSON (با پسوند \fB\&.json\fR) در مجموعه‌ای از دایرکتوری‌های قلاب پیکربندی می‌شوند.
دایرکتوری پیش‌فرض \fB/usr/share/containers/oci/hooks.d\fR است، اما ابزارهایی که این ساختار را مصرف می‌کنند ممکن است این پیش‌فرض را تغییر دهند، دایرکتوری‌های اضافی را در بر گیرند یا روش‌هایی را برای تنظیم دایرکتوری‌های پیکربندی در اختیار فراخواننده‌های خود قرار دهند.

.PP
اگر چندین دایرکتوری پیکربندی شده باشند، نام یک فایل JSON در یک دایرکتوری با اولویت بالاتر، ورودی‌های دارای همان نام فایل در دایرکتوری‌های با اولویت پایین‌تر را می‌پوشاند (mask می‌کند). به عنوان مثال، اگر یک ابزار مصرف‌کننده قلاب‌ها را در \fB/etc/containers/oci/hooks.d\fR و \fB/usr/share/containers/oci/hooks.d\fR (به ترتیب کاهش اولویت) جستجو کند، آنگاه تعریف قلاب در \fB/etc/containers/oci/hooks.d/01-my-hook.json\fR هر تعریفی در \fB/usr/share/containers/oci/hooks.d/01-my-hook.json\fR را پوشش خواهد داد.

.PP
ابزارهایی که از این ساختار استفاده می‌کنند همچنین می‌توانند دایرکتوری‌های قلاب را برای تغییرات تحت نظر بگیرند؛ در این صورت، بدون نیاز به راه‌اندازی مجدد یا ارسال سیگنال، متوجه افزوده‌شدن، تغییرات و حذف فایل‌های JSON خواهند شد. هنگامی که ابزار چندین دایرکتوری قلاب را نظارت می‌کند، تقدم و اولویت بحث‌شده در پاراگراف پیشین همچنان اعمال می‌شود. به عنوان مثال، اگر یک ابزار مصرف‌کننده قلاب‌ها را در \fB/etc/containers/oci/hooks.d\fR و \fB/usr/share/containers/oci/hooks.d\fR (به ترتیب اولویت کاهشی) بررسی کند، نوشتن تعریف جدید یک قلاب در \fB/etc/containers/oci/hooks.d/01-my-hook.json\fR قلابی را که قبلاً از \fB/usr/share/containers/oci/hooks.d/01-my-hook.json\fR بارگذاری شده بود پنهان می‌کند. تغییرات بعدی روی \fB/usr/share/containers/oci/hooks.d/01-my-hook.json\fR تا زمانی که \fB/etc/containers/oci/hooks.d/01-my-hook.json\fR وجود دارد هیچ تأثیری بر ابزار نخواهد داشت. حذف \fB/etc/containers/oci/hooks.d/01-my-hook.json\fR سبب بارگذاری مجدد قلاب از \fB/usr/share/containers/oci/hooks.d/01-my-hook.json\fR خواهد شد.

.PP
قلاب‌ها به ترتیبی تزریق می‌شوند که از مرتب‌سازی نام فایل‌های JSON، پس از تبدیل به حروف کوچک و بر اساس کدهای یونیکد آن‌ها، به دست می‌آید.
برای نمونه، یک قلاب منطبق تعریف‌شده در \fB01-my-hook.json\fR پیش از قلاب‌های منطبق تعریف‌شده در \fB02-another-hook.json\fR و \fB01-UPPERCASE.json\fR تزریق خواهد شد.
اکیداً توصیه می‌شود که ترتیب مرتب‌سازی را با تکیه بر یک پیشوند کاملاً اسکی (مانند \fB01\fR/\fB02\fR در بالا) واضح و بدون ابهام سازید.

.PP
هر فایل JSON باید حاوی شیئی مطابق با یکی از طرح‌واره‌های (schemas) زیر باشد.

.SH "طرح‌واره قلاب ۱.۰.۰ (1.0.0 Hook Schema)"
\fBversion\fR (رشته الزامی)
  نسخه تعریف قلاب را تعیین می‌کند. برای نسخه این طرح‌واره، مقدار باید \fB1.0.0\fR باشد.

.PP
\fBhook\fR (شیء الزامی)
  قلاب مورد نظر برای تزریق، همراه با طرح‌واره ورودی قلاب تعریف‌شده توسط مشخصات زمان اجرای OCI نسخه 1.0.2.

.PP
\fBwhen\fR (شیء الزامی)
  شرایطی که تحت آن قلاب تزریق می‌شود. ویژگی‌های زیر می‌توانند مشخص شوند و حداقل یکی از آن‌ها باید تعیین گردد:
.IP \(bu 2
\fBalways\fR (بولی اختیاری)
  اگر برابر با \fBtrue\fR تنظیم شود، این شرط منطبق می‌گردد.
.IP \(bu 2
\fBannotations\fR (شیء اختیاری)
  اگر تمام جفت‌های کلید/مقدار \fBannotations\fR با یک جفت کلید/مقدار از یادداشت‌های پیکربندی‌شده مطابقت داشته باشند، این شرط برقرار است.
  هر دو کلیدها و مقادیر باید عبارات باقاعده گسترده POSIX باشند.
.IP \(bu 2
\fBcommands\fR (آرایه‌ای اختیاری از رشته‌ها)
  اگر مقدار پیکربندی‌شده \fBprocess.args[0]\fR با یک ورودی مطابقت داشته باشد، این شرط برقرار می‌شود.
  ورودی‌ها باید عبارات باقاعده گسترده POSIX باشند.
.IP \(bu 2
\fBhasBindMounts\fR (بولی اختیاری)
  اگر \fBhasBindMounts\fR برابر با true باشد و فراخواننده درخواست اتصالات متصل‌شونده (bind mounts) میزبان به کانتینر را داده باشد، این شرط برقرار است.

.PP
\fBstages\fR (آرایه‌ای الزامی از رشته‌ها)
  مراحلی که قلاب باید در طول آن‌ها تزریق شود. ورودی‌ها باید از مراحل قلاب مشخصات زمان اجرای OCI نسخه 1.0.2 یا از مراحل توسعه‌یافته پشتیبانی‌شده توسط مصرف‌کننده بسته انتخاب شوند.

.PP
اگر \fIتمام\fP شرایط تعیین‌شده در \fBwhen\fR برقرار باشند، آنگاه \fBhook\fR باید در مراحلی که در \fBstages\fR مشخص شده‌اند تزریق گردد.

.SH "طرح‌واره قلاب ۰.۱.۰ (0.1.0 Hook Schema)"
\fBhook\fR (رشته الزامی)
  مقدار \fBpath\fR را در قلاب تزریق‌شده مشخص می‌کند.

.PP
\fBarguments\fR (آرایه‌ای اختیاری از رشته‌ها)
  آرگومان‌های اضافی برای ارسال به قلاب. آرگومان‌های \fBargs\fR قلاب تزریق‌شده در واقع همان \fBhook\fR به همراه \fBarguments\fR اضافه شده است.

.PP
\fBstages\fR (آرایه‌ای الزامی از رشته‌ها)
  مراحلی که قلاب باید تزریق شود. \fBstage\fR یک مترادف مجاز برای این ویژگی است، اما نباید همزمان هر دوی \fBstages\fR و \fBstage\fR را تعیین کنید. ورودی‌ها باید از مراحل قلاب مشخصات زمان اجرای OCI نسخه 1.0.2 یا مراحل توسعه پشتیبانی‌شده توسط مصرف‌کننده بسته انتخاب شوند.

.PP
\fBcmds\fR (آرایه‌ای اختیاری از رشته‌ها)
  اگر مقدار پیکربندی‌شده \fBprocess.args[0]\fR با یک ورودی تطابق داشته باشد، قلاب باید تزریق شود. \fBcmd\fR مترادفی مجاز برای این مشخصه است، اما نباید هر دوی \fBcmds\fR و \fBcmd\fR را با هم تنظیم کنید. ورودی‌ها باید عبارات باقاعده گسترده POSIX باشند.

.PP
\fBannotations\fR (آرایه‌ای اختیاری از رشته‌ها)
  اگر یک ورودی \fBannotations\fR با مقداری از یادداشت‌های پیکربندی‌شده مطابقت داشته باشد، قلاب باید تزریق شود. \fBannotation\fR مترادفی مجاز برای این ویژگی است، اما نباید همزمان \fBannotations\fR و \fBannotation\fR را با هم مشخص نمایید. ورودی‌ها باید عبارات باقاعده تعمیم‌یافته POSIX باشند.

.PP
\fBhasbindmounts\fR (بولی اختیاری)
  اگر \fBhasBindMounts\fR برابر با true باشد و فراخواننده درخواست اتصالات بایند میزبان به کانتینر را داده باشد، قلاب باید تزریق شود.


.SH "مثال‌ها (EXAMPLES)"
.SS "طرح‌واره قلاب ۱.۰.۰"
پیکربندی زیر قلاب \fBoci-systemd-hook\fR را در مراحل پیش از شروع (pre-start) و پس از توقف (post-stop) تزریق می‌کند، در صورتی که \fBprocess.args[0]\fR به \fB/init\fR یا \fB/systemd\fR ختم شود:

.EX
$ cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
{
  "version": "1.0.0",
  "hook": {
    "path": "/usr/libexec/oci/hooks.d/oci-systemd-hook"
  },
  "when": {
    "commands": [".*/init$" , ".*/systemd$"]
  },
  "stages": ["prestart", "poststop"]
}
.EE

.PP
مثال زیر در صورت پیکربندی کانتینر برای متصل کردن دایرکتوری‌های میزبان به داخل کانتینر (bind-mount)، قلاب \fBoci-umount --debug\fR را در مرحله پیش از شروع تزریق می‌کند.

.EX
$ cat /etc/containers/oci/hooks.d/oci-umount.json
{
  "version": "1.0.0",
  "hook": {
    "path": "/usr/libexec/oci/hooks.d/oci-umount",
    "args": ["oci-umount", "--debug"],
  },
  "when": {
    "hasBindMounts": true
  },
  "stages": ["prestart"]
}
.EE

.PP
مثال زیر دستور \fBnvidia-container-runtime-hook prestart\fR را به همراه متغیرهای محیطی مشخص در مرحله پیش از شروع تزریق می‌کند، اگر کانتینر با یک ورودی \fBannotations\fR پیکربندی شده باشد که کلید آن با \fB^com\\.example\\.department$\fR و مقدار آن با \fB\&.*fluid-dynamics.*\fR مطابقت کند.

.EX
$ cat /etc/containers/oci/hooks.d/nvidia.json
{
  "version": "1.0.0",
  "hook": {
    "path": "/usr/sbin/nvidia-container-runtime-hook",
    "args": ["nvidia-container-runtime-hook", "prestart"],
    "env": [
      "NVIDIA_REQUIRE_CUDA=cuda>=9.1",
      "NVIDIA_VISIBLE_DEVICES=GPU-fef8089b"
    ]
  },
  "when": {
    "annotations": {
      "^com\\\\.example\\\\.department$": ".*fluid-dynamics$"
    }
  },
  "stages": ["prestart"]
}
.EE

.SS "طرح‌واره قلاب ۰.۱.۰"
پیکربندی زیر در صورتی که \fBprocess.args[0]\fR به \fB/init\fR یا \fB/systemd\fR ختم شود، قلاب \fBoci-systemd-hook\fR را در مراحل pre-start و post-stop تزریق می‌نماید:

.EX
$ cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
{
  "cmds": [".*/init$" , ".*/systemd$"],
  "hook": "/usr/libexec/oci/hooks.d/oci-systemd-hook",
  "stages": ["prestart", "poststop"]
}
.EE

.PP
مثال زیر در صورتی که کانتینر برای اتصال دایرکتوری‌های میزبان به داخل کانتینر پیکربندی شده باشد، دستور \fBoci-umount --debug\fR را در مرحله پیش از شروع تزریق می‌کند.

.EX
$ cat /etc/containers/oci/hooks.d/oci-umount.json
{
  "hook": "/usr/libexec/oci/hooks.d/oci-umount",
  "arguments": ["--debug"],
  "hasbindmounts": true,
  "stages": ["prestart"]
}
.EE

.PP
مثال زیر در صورتی که کانتینر با ورودی \fBannotations\fR که مقدار آن با \fB\&.*fluid-dynamics.*\fR تطابق دارد پیکربندی شده باشد، قلاب \fBnvidia-container-runtime-hook prestart\fR را در مرحله پیش از شروع تزریق می‌کند.

.EX
$ cat /etc/containers/oci/hooks.d/osystemd-hook.json
{
  "hook": "/usr/sbin/nvidia-container-runtime-hook",
  "arguments": ["prestart"],
  "annotations: [".*fluid-dynamics.*"],
  "stages": ["prestart"]
}
.EE


.SH "همچنین ببینید (SEE ALSO)"
\fBoci-systemd-hook(1)\fR, \fBoci-umount(1)\fR, \fBlocale(7)\fR
.IP \(bu 2
OCI Runtime Specification, 1.0.2, POSIX-platform hooks
\[la]https://github.com/opencontainers/runtime\-spec/blob/v1.0.2/config.md#posix\-platform\-hooks\[ra]
.IP \(bu 2
OCI Runtime Specification, 1.0.2, process
\[la]https://github.com/opencontainers/runtime\-spec/blob/v1.0.2/config.md#process\[ra]
.IP \(bu 2
POSIX extended regular expressions (EREs)
\[la]https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04\[ra]