.nh
.TH CONTAINERS-REGISTRIES.CONF 5 "اوت ۲۰۱۷" "Containers" "راهنمای لینوکس"

.SH "نام (NAME)"
containers-registries.conf \- ساختار و نحو فایل پیکربندی رجیستری‌های کانتینر در سراسر سیستم


.SH "توضیحات (DESCRIPTION)"
فایل پیکربندی CONTAINERS-REGISTRIES یک فایل پیکربندی در سطح کل سیستم برای رجیستری‌های ایمیج کانتینر است. قالب این فایل TOML است.

.PP
به‌طور پیش‌فرض، در صورت وجود، پیکربندی از مسیر \fB$XDG_CONFIG_HOME/containers/registries.conf\fR (یا اگر \fB$XDG_CONFIG_HOME\fR تنظیم نشده باشد از \fB$HOME/.config/containers/registries.conf\fR) خوانده می‌شود؛ در غیر این صورت از \fB/etc/containers/registries.conf\fR؛ و در غیر این صورت از \fB/usr/share/containers/registries.conf\fR خوانده خواهد شد. برنامه‌ها ممکن است امکان استفاده از مسیر پیکربندی دیگری را به جای این مسیرها فراهم کنند.

.PP
اگر متغیر محیطی \fBCONTAINERS_REGISTRIES_CONF\fR تنظیم شده باشد، فایل پیکربندی مورد استفاده را مشخص می‌کند، مگر آنکه با پیکربندی اختصاصی برنامه بازنویسی شود. در صورت تنظیم بودن این متغیر محیطی، دایرکتوری‌های الحاقی (drop-in) زیر خوانده نخواهند شد.

.PP
علاوه بر registries.conf، فایل‌های الحاقی با همان قالب از دایرکتوری‌های زیر نیز خوانده می‌شوند:
 - \fB$XDG_CONFIG_HOME/containers/registries.conf.d\fR (یا در صورت تنظیم نبودن \fB$XDG_CONFIG_HOME\fR از \fB$HOME/.config/containers/registries.conf.d\fR)
 - \fB/etc/containers/registries.rootful.conf.d\fR (تنها هنگام اجرا به عنوان uid 0)
 - \fB/etc/containers/registries.rootless.conf.d/$UID\fR (تنها هنگام اجرا با uid > 0)
 - \fB/etc/containers/registries.rootless.conf.d\fR (تنها هنگام اجرا با uid > 0)
 - \fB/etc/containers/registries.conf.d\fR
 - \fB/usr/share/containers/registries.rootful.conf.d\fR (تنها هنگام اجرا به عنوان uid 0)
 - \fB/usr/share/containers/registries.rootless.conf.d/$UID\fR (تنها هنگام اجرا با uid > 0)
 - \fB/usr/share/containers/registries.rootless.conf.d\fR (تنها هنگام اجرا با uid > 0)
 - \fB/usr/share/containers/registries.conf.d\fR

.PP
فایل‌ها حتماً باید از پسوند \fB\&.conf\fR استفاده کنند، دایرکتوری‌ها یا فایل‌های دارای پسوندهای دیگر نادیده گرفته می‌شوند. تمامی فایل‌ها از این مسیرها ابتدا جمع‌آوری شده و سپس بر اساس ترتیب الفبایی-عددی مرتب می‌شوند. اگر نام فایل یکسانی دو بار تکرار شده باشد، تنها اولین تطابق از فهرست دایرکتوری‌های فوق استفاده می‌شود. سپس فایل‌ها به ترتیب مرتب‌شده تجزیه و خوانده می‌شوند.

.PP
به عنوان مثال فایل‌های زیر را در نظر بگیرید:
.IP \(bu 2
\fB/usr/share/containers/registries.rootless.conf.d/50-middle.conf\fR
.IP \(bu 2
\fB/etc/containers/registries.rootless.conf.d/20-first.conf\fR
.IP \(bu 2
\fB/etc/containers/registries.rootless.conf.d/70-last.conf\fR

.PP
این فایل‌ها به ترتیب \fB20-first.conf\fR، سپس \fB50-middle.conf\fR و نهایتاً \fB70-last.conf\fR خوانده می‌شوند؛ خود مسیر دایرکتوری در ترتیب خواندن نقشی ندارد و فقط نام پایه (basename) فایل موثر است.

.PP
فیلدهای مشخص‌شده در یک فایل conf تنظیمات قبلی را بازنویسی خواهند کرد. به عنوان مثال، تنظیم \fBunqualified-search-registries\fR در فایل \fB/etc/containers/registries.conf.d/myregistries.conf\fR تنظیمات قبلی در \fB/etc/containers/registries.conf\fR را بازنویسی می‌کند. جدول‌های \fB[[registry]]\fR در صورت یکسان بودن پیشوندها با بازنویسی آیتم‌های موجود ادغام می‌شوند، و موارد جدید نیز اضافه می‌گردند.

.PP
اگر متغیر محیطی \fBCONTAINERS_REGISTRIES_CONF_OVERRIDE\fR تنظیم شده باشد، یک مسیر اضافی را مشخص می‌کند که در پایان همه خوانده می‌شود، مگر آنکه با پیکربندی اختصاصی برنامه بازنویسی شود.

.PP
برای توضیحات دقیق‌تر درباره نحوه بارگذاری این فایل‌ها، به \fBcontainers-config(5)\fP مراجعه کنید.

.SS "تنظیمات عمومی (GLOBAL SETTINGS)"
.TP
\fBunqualified-search-registries\fR
آرایه‌ای از رجیستری‌های \fIhost\fP[\fB:\fR\fIport\fP] که به ترتیب هنگام دریافت (pull) یک ایمیج بدون نام کامل (unqualified) امتحان می‌شوند.

.TP
\fBcredential-helpers\fR
آرایه‌ای از برنامه‌های کمکی گواهی اعتبارسنجی پیش‌فرض که به عنوان مخازن خارجی گواهی استفاده می‌شوند. توجه داشته باشید که "containers-auth.json" یک مقدار رزروشده برای استفاده از فایل‌های احراز هویت طبق مشخصات containers-auth.json(5) است. در صورت مشخص نشدن هیچ مقداری، برنامه‌های کمکی روی \fB["containers-auth.json"]\fR تنظیم می‌شوند.

.TP
\fBadditional-layer-store-auth-helper\fR
رشته‌ای حاوی نام باینری کمکی. این گزینه ارسال اطلاعات اعتبارسنجی رجیستری به یک «مخزن لایه اضافی» (Additional Layer Store) را هر بار که ایمیجی با پروتکل انتقال \fBdocker://\fR خوانده می‌شود، امکان‌پذیر می‌سازد تا بتواند به رجیستری‌های خصوصی دسترسی پیدا کند. برای جزئیات بیشتر به بخش «فعال‌سازی دسترسی Additional Layer Store به رجیستری‌های خصوصی» در زیر مراجعه فرمایید.

.SS "تنظیمات دارای فضای نام [[registry]]"
بخش عمده پیکربندی به صورت آرایه‌ای از جدول‌های TOML از نوع \fB[[registry]]\fR نمایش داده می‌شود؛ بنابراین تنظیمات ممکن است در میان رجیستری‌های مختلف و همچنین در میان فضاهای نام/مخازن مختلف درون یک رجیستری متفاوت باشد.

.SS "انتخاب جدول TOML از نوع [[registry]]"
بر اساس نام یک ایمیج، یک جدول TOML از نوع \fB[[registry]]\fR بر مبنای فیلد \fBprefix\fR آن انتخاب می‌شود.

.PP
\fBprefix\fR: پیشوندی از نام ایمیج مشخص‌شده توسط کاربر، به یکی از قالب‌های زیر:
  - \fIhost\fP[\fB:\fR\fIport\fP]
  - \fIhost\fP[\fB:\fR\fIport\fP]\fB/\fR\fInamespace\fP[\fB/\fR_namespace_…]
  - \fIhost\fP[\fB:\fR\fIport\fP]\fB/\fR\fInamespace\fP[\fB/\fR_namespace_…]\fB/\fR\fIrepo\fP
  - \fIhost\fP[\fB:\fR\fIport\fP]\fB/\fR\fInamespace\fP[\fB/\fR_namespace_…]\fB/\fR\fIrepo\fP(\fB:\fR_tag|\fB@\fR\fIdigest\fP)
  - [\fB*.\fR]\fIhost\fP

.PP
نام ایمیج ارائه‌شده توسط کاربر باید با \fBprefix\fR مشخص‌شده شروع شود (و با جداکننده مناسب ادامه یابد) تا یک جدول TOML از نوع \fB[[registry]]\fR خاص در نظر گرفته شود؛ (تنها) جدول TOML با طولانی‌ترین تطابق استفاده خواهد شد. این مقدار همچنین می‌تواند شامل زیردامنه‌های عمومی با نویسه ستاره (wildcard) در قالب \fB*.example.com\fR باشد. نویسه ستاره فقط باید در ابتدا و مطابق با قالب‌های فوق قرار گیرد. موارد دیگر کار نخواهند کرد؛ برای مثال، \fB*.example.com\fR معتبر است اما \fBexample.*.com\fR، \fB*.example.com/foo\fR و \fB*.example.com:5000/foo/bar:baz\fR معتبر نیستند. توجه داشته باشید که \fB*\fR با هر تعداد زیردامنه دلخواه تطابق دارد؛ بنابراین \fB*.example.com\fR با \fBbar.example.com\fR، \fBfoo.bar.example.com\fR و غیره مطابقت خواهد داشت.

.PP
به عنوان یک حالت خاص، فیلد \fBprefix\fR می‌تواند حذف شود؛ در این صورت، مقدار پیش‌فرض آن برابر با مقدار فیلد \fBlocation\fR (که در زیر توضیح داده شده) خواهد بود.

.SS "تنظیمات به ازای هر فضای نام (Per-namespace settings)"
.TP
\fBinsecure\fR
مقدار \fBtrue\fR یا \fBfalse\fR\&.
به طور پیش‌فرض، موتورهای اجرای کانتینر هنگام بازیابی ایمیج‌ها از یک رجیستری به TLS نیاز دارند. اگر \fBinsecure\fR برابر با \fBtrue\fR تنظیم شود، اتصالات HTTP رمزنگاری‌نشده و همچنین اتصالات TLS با گواهینامه‌های غیرقابل اعتماد مجاز خواهند بود.

.TP
\fBblocked\fR
مقدار \fBtrue\fR یا \fBfalse\fR\&.
اگر \fBtrue\fR باشد، دریافت (pull) ایمیج‌های دارای نام منطبق ممنوع است.

.SS "بازتوزیع و آینه‌سازی رجیستری‌ها (Remapping and mirroring registries)"
ارجاع ایمیج مشخص‌شده توسط کاربر در وهله اول یک نام ایمیج «منطقی» است که همواره برای نام‌گذاری ایمیج استفاده می‌شود. به طور پیش‌فرض، ارجاع ایمیج مستقیماً رجیستری و مخزن مورد استفاده را نیز تعیین می‌کند، اما گزینه‌های زیر می‌توانند برای هدایت دسترسی‌های زیرین به سرورها یا مکان‌های رجیستری دیگر استفاده شوند (برای مثال جهت پشتیبانی از پیکربندی‌های بدون دسترسی به اینترنت بدون نیاز به تغییر فایل‌های \fBDockerfile\fR، یا افزودن افزونگی و پایداری).
.TP
\fBlocation\fR
همان قالب فیلد \fBprefix\fR را می‌پذیرد و مکان فیزیکی فضای نام ریشه‌گرفته از \fBprefix\fR را مشخص می‌کند.

.PP
به طور پیش‌فرض، این مقدار برابر با \fBprefix\fR است (که در این حالت می‌توان \fBprefix\fR را حذف کرد و جدول TOML از نوع \fB[[registry]]\fR فقط \fBlocation\fR را مشخص کند).

.PP
مثال: با فرض

.EX
prefix = "example.com/foo"
location = "internal-registry-for-example.com/bar"
.EE

.PP
درخواست‌ها برای ایمیج \fBexample.com/foo/myimage:latest\fR در عمل با ایمیج \fBinternal-registry-for-example.com/bar/myimage:latest\fR کار خواهند کرد.

.PP
در صورتی که \fBprefix\fR شامل نویسه ستاره در قالب "*.example.com" برای تطبیق زیردامنه باشد، مکان می‌تواند خالی باشد. در چنین حالتی، تطبیق پیشوند انجام می‌شود اما هیچ بازنویسی ارجاعی صورت نخواهد گرفت. رشته اولیه ایمیج درخواست‌شده دست‌نخورده استفاده می‌شود، اما سایر تنظیمات مانند \fBinsecure\fR / \fBblocked\fR / \fBmirrors\fR بر روی ایمیج‌های منطبق اعمال خواهد شد.

.PP
مثال: با فرض

.EX
prefix = "*.example.com"
.EE

.PP
درخواست‌ها برای ایمیج \fBblah.example.com/foo/myimage:latest\fR همان‌طور که هستند استفاده می‌شوند، اما تنظیمات دیگری مانند insecure/blocked/mirrors بر روی ایمیج‌های منطبق اعمال خواهند شد.
.TP
\fBmirror\fR
آرایه‌ای از جدول‌های TOML که آینه‌های (احتمالاً جزئی) را برای فضای نام ریشه‌گرفته از \fBprefix\fR (یعنی جدول TOML جاری \fB[[registry]]\fR) مشخص می‌کند.

.PP
آینه‌ها به ترتیب مشخص‌شده مورد آزمایش قرار می‌گیرند؛ نخستین آینه‌ای که قابل اتصال باشد و ایمیج را در بر داشته باشد استفاده خواهد شد (و اگر هیچ‌یک از آینه‌ها حاوی ایمیج نباشند، مکان اصلی مشخص‌شده در فیلد \fBregistry.location\fR، یا ارجاع دست‌نخورده مشخص‌شده توسط کاربر، به عنوان آخرین گزینه امتحان می‌شود). اگر واکشی لایه‌های باینری (blob) بعداً روی منبع انتخاب‌شده با شکست روبرو شود، منابع باقی‌مانده به طور خودکار امتحان می‌شوند (به بخش \fBجایگزینی آینه در سطح Blob\fP در زیر مراجعه فرمایید).

.PP
هر جدول TOML در آرایه \fBmirror\fR می‌تواند شامل فیلدهای زیر باشد:
- \fBlocation\fR: همان معنای مشخص‌شده در جدول TOML از نوع \fB[[registry]]\fR
- \fBinsecure\fR: همان معنای مشخص‌شده در جدول TOML از نوع \fB[[registry]]\fR
- \fBpull-from-mirror\fR: مقادیر \fBall\fR، \fBdigest-only\fR یا \fBtag-only\fR\&. در حالت "digest-only"، آینه‌ها فقط برای دریافت بر اساس هش (digest) استفاده خواهند شد. دریافت ایمیج‌ها بر اساس تگ بسته به اینکه از چه نقطه‌ای ایمیج دریافت شود می‌تواند ایمیج‌های متفاوتی حاصل کند. محدود کردن آینه‌ها به دریافت بر اساس هش از این مشکل جلوگیری می‌کند. در حالت "tag-only"، آینه‌ها فقط برای دریافت بر اساس تگ استفاده خواهند شد. برای یک آینه به‌روزتر و پرهزینه‌تر که کمتر احتمال ناهماهنگی در تغییر تگ‌ها دارد، نباید بی‌دلیل برای ارجاعات بر اساس هش استفاده شود. حالت پیش‌فرض "all" است (یا خالی رها شود)، که در آن آینه‌ها هم برای دریافت با هش و هم با تگ استفاده می‌شوند، مگر اینکه گزینه mirror-by-digest-only برای رجیستری اصلی تنظیم شده باشد.
توجه داشته باشید که این تنظیم به ازای هر آینه تنها زمانی مجاز است که \fBmirror-by-digest-only\fR برای رجیستری اصلی تنظیم نشده باشد.
.TP
\fBmirror-by-digest-only\fR
مقدار \fBtrue\fR یا \fBfalse\fR\&.
اگر \fBtrue\fR باشد، آینه‌ها تنها زمانی در حین دریافت استفاده می‌شوند که ارجاع ایمیج شامل یک هش (digest) باشد.
توجه داشته باشید که اگر همه آینه‌ها روی digest-only تنظیم شوند، ایمیج‌های دارای تگ تنها از رجیستری اصلی استفاده خواهند کرد.
اگر همه آینه‌ها روی tag-only تنظیم شوند، ایمیج‌های دارای هش تنها از رجیستری اصلی استفاده خواهند کرد.

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

.SS "جایگزینی آینه در سطح Blob (Blob-level mirror fallback)"
پس از انتخاب منبع دریافت بر اساس در دسترس بودن مانیفست، دریافت بلوک‌های داده منفرد یا همان لایه‌ها (blobs) ممکن است همچنان با شکست مواجه شود. هنگامی که واکشی یک لایه با یک خطای گذرا (مانند خطای سرور HTTP 5xx یا وقفه زمانی شبکه)، خطای \fBBLOB_UNKNOWN\fR، یا خطای HTTP 429 پس از تلاش‌های مجدد توکار با شکست روبرو شود، منابع پیکربندی‌شده باقی‌مانده به ترتیب آزمایش می‌شوند. در صورت یافتن یک منبع فعال، از آن برای دریافت لایه‌های بعدی در همان عملیات pull استفاده می‌شود.

.PP
این بدان معناست که حتی اگر منبع انتخاب‌شده بتواند مانیفست را ارائه دهد، واکشی لایه‌ها می‌تواند یک بار به صورت شفاف روی همان منبع تلاش مجدد کند و سپس بدون راه‌اندازی مجدد کل فرآیند دریافت، به آینه دیگر یا رجیستری اصلی جابجا شود.

.PP
این جایگزینی یا تلاش مجدد افزون بر تلاش مجدد در سطح فراخواننده (مانند بسته \fBretry\fR در \fBcontainers-common\fR یا تلاش‌های مجدد در kubelet) کار می‌کند. واکشی یک لایه ممکن است پیش از جابجایی یک بار روی همان منبع مجدداً امتحان شود، و فراخواننده ممکن است علاوه بر آن، کل عملیات دریافت را نیز دوباره تکرار کند.

.PP
\fIنکته\fP: تغییر مسیر و آینه‌ها در حال حاضر تنها هنگام خواندن یک ایمیج منفرد پردازش می‌شوند، نه هنگام ارسال (push) به یک رجیستری یا انجام هر نوع جستجو/وارسی دیگر در رجیستری. این وضعیت ممکن است در آینده تغییر کند.

.SS "نام مستعار برای نام‌های کوتاه (Short-Name Aliasing)"
استفاده از رجیستری‌های جستجوی بدون نام کامل (unqualified-search) متضمن ابهام است، زیرا مشخص نیست که یک ایمیج داده‌شده با نام کوتاه از کدام رجیستری باید دریافت شود.

.PP
همان‌طور که در یادداشت انتهای این صفحه راهنما اشاره شده است، استفاده از نام‌های کوتاه در معرض خطر تصاحب فضاهای نام رجیستری (namespace squatting) قرار دارد. اگر رجیستری‌های جستجو روی \fB["registry1.com", "registry2.com"]\fR تنظیم شده باشند، یک مهاجم ممکن است فضای نامی در registry1.com را به تصرف درآورد به طوری که یک ایمیج به جای منبع مورد نظر در registry2.com، از registry1.com دریافت شود.

.PP
در حالی که استفاده همیشگی از ارجاعات کامل ایمیج به شدت توصیه می‌شود، ممکن است تغییر پیاده‌سازی‌های موجود که از نام‌های کوتاه استفاده می‌کنند آسان نباشد. برای دور زدن ابهام مذکور، می‌توان اصطلاحاً «نام‌های مستعار کوتاه» (short-name aliases) را پیکربندی کرد که به ارجاع کامل ایمیج اشاره می‌کنند.

.PP
نام‌های مستعار کوتاه را می‌توان در جدول \fB[aliases]\fR به صورت \fB"name"="value"\fR پیکربندی کرد که در آن \fBname\fR در سمت چپ همان نام کوتاه (مانند "image") و \fBvalue\fR در سمت راست همان ارجاع کامل ایمیج (مانند "registry.com/namespace/image") است. توجه داشته باشید که نه "name" و نه "value" نمی‌توانند شامل تگ یا هش باشند. علاوه بر این، "name" باید یک نام کوتاه باشد و بنابراین نمی‌تواند شامل دامنه رجیستری باشد یا به localhost اشاره کند.

.PP
هنگام دریافت با یک نام کوتاه، جدول نام‌های مستعار پیکربندی‌شده برای حل نام کوتاه استفاده می‌شود. اگر یک نام مستعار منطبق پیدا شود، بدون مراجعه به فهرست رجیستری‌های جستجوی بدون نام کامل استفاده خواهد شد. اگر نام مستعار منطبقی یافت نشود، رفتار سیستم از طریق گزینه \fBshort-name-mode\fR به گونه‌ای که در زیر توضیح داده شده، کنترل می‌شود.

.PP
توجه داشته باشید که تگ‌ها و هش‌ها برای حل نام مستعار از نام کوتاه مشخص‌شده توسط کاربر جدا می‌شوند. بنابراین، "image"، "image:tag" و "image@digest" همگی به یک نام مستعار واحد (یعنی "image") حل می‌شوند. تگ‌ها و هش‌های جداشده بعداً به نام مستعار دریافت‌شده متصل خواهند شد.

.PP
همچنین توجه داشته باشید که فایل‌های پیکربندی الحاقی (به containers-registries.conf.d(5) مراجعه کنید) می‌توانند نام‌های مستعار را در ترتیب بارگذاری خاص فایل‌ها بازنویسی کنند. اگر مقدار "value" یک نام مستعار خالی باشد (یعنی "")، نام مستعار حذف خواهد شد. با این حال، یک "name" داده‌شده تنها یک بار می‌تواند در یک فایل پیکربندی منفرد مشخص شود.

.SS "نام‌های مستعار کوتاه: حالت‌ها (Modes)"
گزینه \fBshort-name-mode\fR از سه حالت برای کنترل رفتار تفکیک نام‌های کوتاه پشتیبانی می‌کند:
.IP \(bu 2
\fBenforcing\fR: اگر تنها یک رجیستری جستجوی unqualified تنظیم شده باشد، از همان استفاده می‌شود زیرا ابهامی وجود ندارد. اگر بیش از یک رجیستری وجود داشته باشد و برنامه کاربر در ترمینال در حال اجرا باشد (یعنی stdout و stdin یک TTY باشند)، از کاربر خواسته می‌شود یکی از رجیستری‌های جستجوی مشخص‌شده را انتخاب کند. اگر برنامه در ترمینال اجرا نشود، ابهام قابل حل نیست و منجر به خطا خواهد شد.
.IP \(bu 2
\fBpermissive\fR: مانند حالت enforcing رفتار می‌کند اما اگر برنامه در ترمینال در حال اجرا نباشد، منجر به بروز خطا نمی‌شود. در عوض، به استفاده از تمامی رجیستری‌های جستجوی unqualified برمی‌گردد.
.IP \(bu 2
\fBdisabled\fR: استفاده از تمام رجیستری‌های جستجوی unqualified بدون درخواست از کاربر.

.PP
اگر \fBshort-name-mode\fR اصلاً مشخص نشده باشد یا خالی رها شود، به طور پیش‌فرض از حالت \fBpermissive\fR استفاده می‌شود. اگر نام کوتاه ارائه‌شده توسط کاربر قبلاً دارای نام مستعار نبوده باشد، حالت‌های \fBenforcing\fR و \fBpermissive\fR در صورت درخواست تایید از کاربر، پس از یک دریافت موفقیت‌آمیز، یک نام مستعار جدید ثبت خواهند کرد. توجه داشته باشید که نام مستعار ثبت‌شده در مسیر \fB/var/cache/containers/short-name-aliases.conf\fR برای کاربر ریشه نوشته می‌شود تا تفکیک واضحی بین فایل‌های registries.conf که احتمالاً توسط انسان ویرایش شده‌اند و فایل ماشین‌ساز \fBshort-name-aliases.conf\fR وجود داشته باشد. برای کاربران بدون ریشه (rootless) از مسیر \fB$HOME/.cache\fR استفاده می‌شود. اگر یک نام مستعار در فایل \fBregistries.conf\fR و همچنین در فایل ماشین‌ساز \fBshort-name-aliases.conf\fR مشخص شده باشد، اولویت با فایل \fBshort-name-aliases.conf\fR خواهد بود.

.SS "نرمال‌سازی ارجاعات docker.io"
داکر هاب \fBdocker.io\fR به شیوه خاصی مدیریت می‌شود: در صورتی که هیچ فضای نام خاص دیگری تعریف نشده باشد (برای مثال در \fBdocker.io/namespace/image\fR)، هر عملیات push و pull در داخل به طور خودکار با \fB/library\fR نرمال‌سازی می‌شود.

.PP
(توجه داشته باشید که این نرمال‌سازی توصیف‌شده دقیقاً منطبق بر رفتار داکر است.)

.PP
این بدان معناست که دریافت \fBdocker.io/alpine\fR در داخل به \fBdocker.io/library/alpine\fR ترجمه می‌شود. دریافت \fBdocker.io/user/alpine\fR بازنویسی نخواهد شد زیرا این آدرس از قبل مسیر دوردست صحیح است.

.PP
بنابراین، برای بازنگاشت یا آینه‌سازی ایمیج‌های \fBdocker.io\fR در فضای نام (ضمنی) \fB/library\fR (یا کل آن فضای نام)، فیلدهای prefix و location در این فایل پیکربندی باید صریحاً شامل آن فضای نام \fB/library\fR باشند؛ برای مثال \fBprefix = "docker.io/library/alpine"\fR و نه \fBprefix = "docker.io/alpine"\fR\&. حالت دوم با مخازن \fBdocker.io/alpine/*\fR تطابق می‌یابد اما با ایمیج \fBdocker.io/[library/]alpine\fR مطابقت نخواهد داشت.

.SS "مثال (EXAMPLE)"
.EX
unqualified-search-registries = ["example.com"]

[[registry]]
prefix = "example.com/foo"
insecure = false
blocked = false
location = "internal-registry-for-example.com/bar"

[[registry.mirror]]
location = "example-mirror-0.local/mirror-for-foo"

[[registry.mirror]]
location = "example-mirror-1.local/mirrors/foo"
insecure = true

[[registry]]
location = "registry.com"

[[registry.mirror]]
location = "mirror.registry.com"
.EE

.PP
با توجه به تنظیمات بالا، دریافت ایمیج \fBexample.com/foo/image:latest\fR موارد زیر را امتحان می‌کند:
.IP "  1." 5
\fBexample-mirror-0.local/mirror-for-foo/image:latest\fR
.IP "  2." 5
\fBexample-mirror-1.local/mirrors/foo/image:latest\fR
.IP "  3." 5
\fBinternal-registry-for-example.com/bar/image:latest\fR

.PP
به ترتیب، و از اولین موردی که بتواند مانیفست را ارائه دهد استفاده خواهد شد. اگر واکشی لایه بعداً روی منبع انتخاب‌شده با شکست مواجه شود، منابع باقی‌مانده مطابق آنچه در بخش \fBجایگزینی آینه در سطح Blob\fP شرح داده شد، امتحان می‌شوند.

.PP
توجه داشته باشید که یک آینه تنها با جدول جاری TOML از نوع \fB[[registry]]\fR مرتبط است. با استفاده از مثال بالا، دریافت ایمیج \fBregistry.com/image:latest\fR تنها به \fBmirror.registry.com\fR متصل می‌شود و آینه‌های مرتبط با \fBexample.com/foo\fR در نظر گرفته نخواهند شد.

.SS "فعال‌سازی دسترسی Additional Layer Store به رجیستری‌های خصوصی"
گزینه \fBadditional-layer-store-auth-helper\fR ارسال اطلاعات اعتبارسنجی رجیستری به یک مخزن لایه اضافی را امکان‌پذیر می‌سازد تا بتواند به رجیستری‌های خصوصی دسترسی پیدا کند.

.PP
هنگام دسترسی به یک رجیستری خصوصی از طریق مخزن لایه اضافی، باید یک باینری کمکی ارائه شود. این فایل باینری از طریق گزینه \fBadditional-layer-store-auth-helper\fR ثبت می‌شود. هر بار که ایمیجی با پروتکل انتقال \fBdocker://\fR خوانده می‌شود، فایل باینری کمکی مشخص‌شده اجرا می‌شود و اطلاعات اعتبارسنجی رجیستری را از ورودی استاندارد (stdin) در قالب زیر دریافت می‌کند:

.EX
{
  "$image_reference": {
    "username": "$username",
    "password": "$password",
    "identityToken": "$identityToken"
  }
}
.EE

.PP
قالب \fB$image_reference\fR به صورت \fB$repo{:$tag|@$digest}\fR است.

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

.SS "مثال (EXAMPLE)"
پیکربندی نمونه زیر دو رجیستری قابل جستجو، یک رجیستری ناامن و دو رجیستری مسدودشده را تعریف می‌کند:

.EX
[registries.search]
registries = ['registry1.com', 'registry2.com']

[registries.insecure]
registries = ['registry3.com']

[registries.block]
registries = ['registry.untrusted.com', 'registry.unsafe.com']
.EE

.SH "هشدار: خطر استفاده از نام‌های ناقص ایمیج (NOTE: RISK OF USING UNQUALIFIED IMAGE NAMES)"
توصیه ما همواره استفاده از نام‌های کامل ایمیج شامل سرور رجیستری (نام کامل dns)، فضای نام، نام ایمیج و تگ است (برای مثال registry.redhat.io/ubi8/ubi:latest). هنگام استفاده از نام‌های کوتاه، همواره این خطر ذاتی وجود دارد که ایمیج در حال دریافت جعل شده باشد. برای مثال، کاربری می‌خواهد ایمیجی به نام \fBfoobar\fR را از یک رجیستری دریافت کند و انتظار دارد که از myregistry.com بیاید. اگر myregistry.com در صدر فهرست جستجو نباشد، یک مهاجم می‌تواند ایمیج \fBfoobar\fR متفاوتی را در یک رجیستری که بالاتر در فهرست جستجو قرار دارد قرار دهد. کاربر به طور تصادفی به جای محتوای مورد نظر، ایمیج و کد مهاجم را دریافت و اجرا خواهد کرد. توصیه می‌کنیم تنها رجیستری‌هایی را اضافه کنید که کاملاً قابل اعتماد هستند؛ یعنی رجیستری‌هایی که به کاربران ناشناس اجازه ساخت حساب‌هایی با نام‌های دلخواه را نمی‌دهند. این امر مانع از جعل ایمیج یا تصاحب نام می‌شود. در صورت ضرورت استفاده از چنین رجیستری‌هایی، باید آن‌ها را در انتهای فهرست قرار داد.

.PP
توصیه می‌شود برای دریافت ایمیج‌ها از نام‌های کاملاً معین (fully-qualified) استفاده شود زیرا رجیستری مقصد کاملاً بدون ابهام خواهد بود. همچنین دریافت از طریق هش (مانند quay.io/repository/name@digest) ابهام احتمالی تگ‌ها را به کلی از بین می‌برد.

.SH "همچنین ببینید (SEE ALSO)"
containers-config(5), containers-auth.json(5), containers-certs.d(5)

.SH "تاریخچه (HISTORY)"
دسامبر ۲۰۱۹، هشدار نام‌های ناقص ایمیج توسط Tom Sweeney tsweeney@redhat.com اضافه شد
\[la]mailto:tsweeney@redhat.com\[ra]

.PP
مارس ۲۰۱۹، قالب پیکربندی اضافی توسط Sascha Grunert sgrunert@suse.com افزوده شد
\[la]mailto:sgrunert@suse.com\[ra]

.PP
اوت ۲۰۱۸، توسط Valentin Rothberg vrothberg@suse.com به containers-registries.conf(5) تغییر نام داد
\[la]mailto:vrothberg@suse.com\[ra]

.PP
ژوئن ۲۰۱۸، توسط Tom Sweeney tsweeney@redhat.com به‌روزرسانی شد
\[la]mailto:tsweeney@redhat.com\[ra]

.PP
اوت ۲۰۱۷، در ابتدا توسط Brent Baude bbaude@redhat.com تدوین شد
\[la]mailto:bbaude@redhat.com\[ra]