.nh
.TH umoci-insert(1) # umoci insert - insert content into an OCI image
Aleksa Sarai
SEPTEMBER 2018

.SH "نام (NAME)"
umoci insert \- درج محتوا در یک تصویر OCI


.SH "خلاصه دستور (SYNOPSIS)"
\fBumoci insert\fP
\fB--image\fP=\fIimage\fP[:\fItag\fP]
[\fB--tag\fP=\fInew-tag\fP]
[\fB--compress\fP=\fIcompression-type\fP]
[\fB--opaque\fP]
[\fB--rootless\fP]
[\fB--uid-map\fP=\fIvalue\fP]
[\fB--uid-map\fP=\fIvalue\fP]
[\fB--no-history\fP]
[\fB--history.comment\fP=\fIcomment\fP]
[\fB--history.created_by\fP=\fIcreated_by\fP]
[\fB--history.author\fP=\fIauthor\fP]
[\fB--history-created\fP=\fIdate\fP]
\fIsource\fP
\fItarget\fP

.PP
\fBumoci insert\fP
[options]
\fB--whiteout\fP
\fItarget\fP


.SH "توضیحات (DESCRIPTION)"
در شکل نخست، محتویات \fIsource\fP را در تصویر OCI مشخص‌شده توسط \fB--image\fP درج می‌کند \-\- \fBآن را رونویسی می‌کند مگر این‌که --tag را مشخص کنید\fP\&. این کار با ایجاد یک لایه جدید حاوی تنها محتویات \fIsource\fP با نام \fItarget\fP انجام می‌شود\&. \fIsource\fP می‌تواند یک فایل یا دایرکتوری باشد، و در حالت دوم به صورت بازگشتی پیمایش خواهد شد. اگر \fB--opaque\fP مشخص شده باشد، هر مسیری زیر \fItarget\fP در لایه‌های پیشین تصویر (با فرض این‌که \fItarget\fP یک دایرکتوری است) حذف خواهد شد.

.PP
در شکل دوم، یک «مدخل حذف» (deletion entry) درون تصویر OCI برای \fItarget\fP درج می‌کند. این کار با درج یک لایه شامل تنها یک مدخل whiteout برای مسیر داده‌شده انجام می‌شود.

.PP
توجه داشته باشید که این دستور با ایجاد یک لایه جدید کار می‌کند، بنابراین نباید برای حذف (یا جایگزینی) اطلاعات محرمانه (secrets) از یک تصویرِ از پیش ساخته‌شده استفاده شود. برای چگونگی انجام درست این کار از طریق ایجاد نکردن لایه‌های حاوی اطلاعات محرمانه از همان ابتدا، \fBumoci-config\fP(1) و \fB--config.volume\fP را ببینید.

.PP
اگر \fB--no-history\fP مشخص نشده باشد، یک مدخل تاریخچه برای این تغییر به تصویر برچسب‌خورده OCI الحاق می‌شود (که پرچم‌های گوناگون \fB--history.\fP مقادیر استفاده‌شده را کنترل می‌کنند). برای مشاهده تاریخچه، \fBumoci-stat\fP(1) را ببینید.


.SH "گزینه‌ها (OPTIONS)"
گزینه‌های عمومی در \fBumoci\fP(1) تعریف شده‌اند.

.PP
\fB--image\fP=\fIimage\fP[:\fItag\fP]
  برچسب مبدأ و مقصد برای درج \fIfile\fP در \fIpath\fP درون تصویر کانتینر. \fIimage\fP باید مسیری به یک تصویر OCI معتبر باشد و \fItag\fP باید یک برچسب معتبر در تصویر باشد. اگر \fItag\fP ارائه نشود، مقدار پیش‌فرض آن "latest" خواهد بود.

.PP
\fB--tag\fP=\fInew-tag\fP
  نام برچسب برای تصویر تغییریافته؛ در صورت عدم تعیین، برچسب اصلی ارائه‌شده به \fB--image\fP بازنویسی خواهد شد.

.PP
\fB--compress\fP=\fIcompression-type\fP
  نوع فشرده‌سازی مورد استفاده هنگام ایجاد یک لایه جدید را مشخص می‌کند. انواع فشرده‌سازی پشتیبانی‌شده عبارتند از \fInone\fP، \fIgzip\fP و \fIzstd\fP\&. دستور \fBumoci-unpack\fP(1) به‌طور شفاف از تمامی روش‌های فشرده‌سازی که می‌توانید با \fB--compress\fP مشخص کنید پشتیبانی می‌کند\&.
  
  مقدار ویژهٔ \fIauto\fP باعث می‌شود \fBumoci\fP(1) مناسب‌ترین الگوریتم فشرده‌سازی را بر اساس روش فشرده‌سازی لایه‌های پیشین به‌طور خودکار انتخاب کند (تلاش خواهد کرد از الگوریتم فشرده‌سازی جدیدترین لایه‌ای که از آن پشتیبانی می‌کند استفاده کند). توجه داشته باشید که \fIauto\fP هرگز فشرده‌سازی \fInone\fP را به‌طور خودکار انتخاب نمی‌کند، زیرا فشرده نکردن آرشیوهای \fBtar\fP(1) به‌هیچ‌وجه توصیه نمی‌شود.
  
  اگر هیچ \fIcompression-type\fP مشخص نشود، مقدار پیش‌فرض \fIauto\fP خواهد بود\&.

.PP
\fB--opaque\fP
  (با فرض این‌که \fItarget\fP یک دایرکتوری است.) یک مدخل سفیدپوشی کدر (opaque whiteout) برای \fItarget\fP اضافه می‌کند تا هر مسیر فرزندی از \fItarget\fP در لایه‌های پیشین توسط مدخل جدید برای \fItarget\fP ماسک شود، که فقط شامل محتویات \fIsource\fP خواهد بود\&. این گزینه امکان جایگزینی کامل یک دایرکتوری را در مقایسه با ادغام مدخل‌های دایرکتوری فراهم می‌کند.

.PP
\fB--whiteout\fP
  یک مدخل حذف برای \fItarget\fP اضافه می‌کند، تا در استخراج‌های بعدی تصویر وجود نداشته باشد.

.PP
\fB--rootless\fP
  پشتیبانی از درج بدون ریشه (rootless) را فعال می‌کند. این قابلیت اجازه می‌دهد \fBumoci-insert\fP(1) توسط کاربر بدون امتیاز استفاده شود. استفاده از این پرچم به معنای اعمال ضمنی \fB--uid-map=0:$(id -u):1\fP و \fB--gid-map=0:$(id -g):1\fP و همچنین فعال‌سازی چندین ویژگی برای شبیه‌سازی بخش‌هایی از فرایند بازگشتی به منظور ایجاد شبیه‌ترین نسخه ممکن از سیستم‌فایل برای درج است.

.PP
\fB--uid-map\fP=\fIvalue\fP
  یک نگاشت UID را برای استفاده هنگام درج فایل‌ها مشخص می‌کند. این گزینه به روشی مشابه با \fBuser_namespaces\fP(7) استفاده می‌شود و به قالب \fBcontainer:host[:size]\fP\& است.

.PP
\fB--gid-map\fP=\fIvalue\fP
  یک نگاشت GID را برای استفاده هنگام درج فایل‌ها مشخص می‌کند. این گزینه به روشی مشابه با \fBuser_namespaces\fP(7) استفاده می‌شود و به قالب \fBcontainer:host[:size]\fP\& است.

.PP
\fB--no-history\fP
  باعث می‌شود هیچ مدخل تاریخچه‌ای برای این عملیات افزوده نشود. \fBاستفاده از این گزینه با umoci-insert(1) توصیه نمی‌شود، زیرا باعث می‌شود تاریخچه شامل تمامی لایه‌های تصویر نباشد \-\- و در نتیجه سبب سردرگمی ابزارهایی خواهد شد که به تاریخچه تصویر نگاه می‌کنند.\fP

.PP
\fB--history.comment\fP=\fIcomment\fP
  توضیح برای مدخل تاریخچهٔ مربوط به این تغییر تصویر. در صورت عدم تعیین، \fBumoci\fP(1) یک مقدار وابسته به پیاده‌سازی تولید خواهد کرد.

.PP
\fB--history.created_by\fP=\fIcreated_by\fP
  مدخل CreatedBy برای مدخل تاریخچهٔ مربوط به این تغییر تصویر. در صورت عدم تعیین، \fBumoci\fP(1) یک مقدار وابسته به پیاده‌سازی تولید خواهد کرد.

.PP
\fB--history.author\fP=\fIauthor\fP
  مقدار پدیدآورنده (Author) برای مدخل تاریخچهٔ مربوط به این تغییر تصویر. در صورت عدم تعیین، این مقدار برابر با مقدار پدیدآورنده تصویر \fBپس از\fP اعمال هرگونه تغییر توسط این فراخوانی از \fBumoci-config\fP(1) خواهد بود.

.PP
\fB--history-created\fP=\fIdate\fP
  تاریخ ایجاد برای مدخل تاریخچهٔ مربوط به این تغییر تصویر. این مقدار باید یک برچسب زمانی با قالب ISO8601 باشد (\fBdate\fP(1) را ببینید). در صورت عدم تعیین، زمان فعلی استفاده می‌شود.


.SH "مثال‌ها (EXAMPLES)"
دستور زیر یک فایل \fBmybinary\fR را در مسیر \fB/usr/bin/mybinary\fR و یک دایرکتوری \fBmyconfigdir\fR را در مسیر \fB/etc/myconfigdir\fR درج می‌کند\&. لازم به ذکر است که اگر \fB/etc/myconfigdir\fR از قبل در تصویر وجود داشته باشد، محتویات دو دایرکتوری ادغام می‌شوند (و لایه جدیدتر اولویت خواهد داشت).

.EX
% umoci insert --image oci:foo mybinary /usr/bin/mybinary
% umoci insert --image oci:foo myconfigdir /etc/myconfigdir
.EE

.PP
و در این مثال‌ها \fB/usr/bin/mybinary\fR را حذف می‌کنیم و کل \fB/etc\fR را با \fBmyetcdir\fR جایگزین می‌کنیم (به‌طوری که هیچ‌یک از مدخل‌های قدیمی \fB/etc\fR هنگام اجرای \fBumoci-unpack\fP(1) وجود نخواهند داشت).

.EX
% umoci insert --image oci:foo --whiteout /usr/bin/mybinary
% umoci insert --image oci:foo --opaque myetcdir /etc
.EE


.SH "همچنین ببینید (SEE ALSO)"
\fBumoci\fP(1), \fBumoci-repack\fP(1), \fBumoci-raw-add-layer\fP(1)