buildah(1) General Commands Manual buildah(1)

buildah - ابزار خط فرمان برای ساخت ایمیجهای کانتینری سازگار با OCI

buildah [گزینه‌ها] COMMAND [ARG...]

بسته Buildah یک ابزار خط فرمان ارائه می‌دهد که می‌تواند برای موارد زیر استفاده شود:

* ایجاد یک کانتینر در حال کار، چه از پایه (scratch) و چه با استفاده از یک ایمیج به عنوان نقطه آغاز.
* سوار کردن (mount) سیستم فایل ریشه یک کانتینر در حال کار جهت دستکاری آن.
* پیاده کردن (unmount) سیستم فایل ریشه یک کانتینر در حال کار.
* استفاده از محتویات به‌روزرسانی‌شده سیستم فایل ریشه کانتینر به عنوان یک لایه سیستم فایل برای ساخت ایمیج جدید.
* حذف یک کانتینر در حال کار یا یک ایمیج.
* تغییر نام یک کانتینر محلی.

--cgroup-manager=manager

مدیر CGroup مورد استفاده برای cgroupهای کانتینر. مقادیر پشتیبانی‌شده عبارتند از cgroupfs یا systemd. مقدار پیش‌فرض systemd است، مگر اینکه در فایل containers.conf بازنویسی شده باشد.

نکته: تنظیم این فلگ می‌تواند هنگام فراخوانی دستورات بر روی کانتینرهایی که قبلاً با نوع مدیر CGroup دیگری ایجاد شده‌اند، باعث بروز مشکل در برخی دستورات شود. نکته: مدیر CGroup در حالت بدون ریشه (rootless) هنگام استفاده از نگارش اول CGroups (یعنی V1) پشتیبانی نمی‌شود.

--imagestore path

مسیری که محتوای ایمیج‌های دریافت‌شده (pulled) و ساخته‌شده در آن ذخیره خواهد شد. به طور پیش‌فرض، مکان پیکربندی‌شده --root هم برای ایمیج‌های دریافت‌شده و ساخته‌شده و هم برای کانتینرها استفاده می‌شود. اگر درایور ذخیره‌سازی overlay باشد، هر ایمیجی که قبلاً در مکان --root نوشته شده باشد همچنان در دسترس خواهد بود.

این گزینه تنظیم imagestore در containers-storage.conf(5) را بازنویسی می‌کند.

--log-level level

سطح گزارش‌گیری مورد استفاده. می‌تواند یکی از مقادیر «trace»، «debug»، «info»، «warn»، «error»، «fatal» یا «panic» باشد؛ مقدار پیش‌فرض «warn» است.

--help, -h

نمایش راهنما.

--registries-conf path

مسیر فایل پیکربندی که مشخص می‌کند هنگام تکمیل نام ایمیج‌هایی که فاقد بخش رجیستری یا دامنه هستند، به کدام رجیستری‌های کانتینر مراجعه شود. استفاده از این گزینه پیشنهاد نمی‌شود، زیرا رفتار پیش‌فرض مبنی بر استفاده از پیکربندی سراسری سیستم (/etc/containers/registries.conf) در بیشتر موارد ترجیح داده می‌شود.

--registries-conf-dir path

مسیر دایرکتوری حاوی قطعه‌های پیکربندی (snippets) که مشخص می‌کنند هنگام تکمیل نام ایمیج‌های فاقد بخش رجیستری یا دامنه، به کدام رجیستری‌ها باید مراجعه شود. استفاده از این گزینه پیشنهاد نمی‌شود، چرا که رفتار پیش‌فرض مبنی بر استفاده از پیکربندی سراسری سیستم (/etc/containers/registries.d) معمولاً ارجح است.

--root path

دایرکتوری ریشه ذخیره‌سازی (پیش‌فرض: «/var/lib/containers/storage» برای UID 0 و «‎$HOME/.local/share/containers/storage» برای سایر کاربران). دایرکتوری ریشه پیش‌فرض در /etc/containers/storage.conf پیکربندی شده است.

--runroot path

دایرکتوری وضعیت ذخیره‌سازی (پیش‌فرض: «/run/containers/storage» برای UID 0 و «‎/run/user/$UID» برای سایر کاربران). دایرکتوری وضعیت پیش‌فرض در /etc/containers/storage.conf پیکربندی شده است.

--short-name-alias-conf path

مسیر فایلی که شامل نگاشت‌های کش‌شده میان نام‌های کوتاه ایمیج و نام‌های کامل متناظر آن‌ها است. این گزینه برای نگاشت نام‌های ایمیج مشخص‌شده با نام‌های کوتاه مانند «ubi8» (که فاقد مؤلفه رجیستری هستند) به یک نام کامل متناظر شامل رجیستری و سایر مؤلفه‌ها، مانند «registry.access.redhat.com/ubi8» استفاده می‌شود. استفاده از این گزینه پیشنهاد نمی‌شود، زیرا رفتار پیش‌فرض مبنی بر استفاده از کش سراسری سیستم (/var/cache/containers/short-name-aliases.conf) یا کش اختصاصی کاربر ($HOME/.cache/containers/short-name-aliases.conf) برای تکمیل پیش‌فرض‌های سراسری سیستم، معمولاً ترجیح داده می‌شود.

--storage-driver value

درایور ذخیره‌سازی. درایور ذخیره‌سازی پیش‌فرض برای UID 0 در /etc/containers/storage.conf (و $HOME/.config/containers/storage.conf در حالت بدون ریشه) پیکربندی شده است، و برای سایر کاربران vfs است. متغیر محیطی STORAGE_DRIVER مقدار پیش‌فرض را بازنویسی می‌کند. درایوری که با --storage-driver مشخص شود بر تمام موارد دیگر اولویت دارد.

مثال‌ها: «overlay»، «vfs»

بازنویسی این گزینه موجب نادیده گرفته شدن تنظیمات storage-opt در /etc/containers/storage.conf خواهد شد. کاربر باید گزینه‌های اضافی را از طریق فلگ --storage-opt مشخص کند.

--storage-opt value

گزینه درایور ذخیره‌سازی. گزینه‌های پیش‌فرض درایور ذخیره‌سازی در /etc/containers/storage.conf (و $HOME/.config/containers/storage.conf در حالت بدون ریشه) پیکربندی شده‌اند. متغیر محیطی STORAGE_OPTS مقدار پیش‌فرض را بازنویسی می‌کند. گزینه‌های مشخص‌شده با --storage-opt بر همه اولویت دارند.

--transient-store bool-value

ذخیره فراداده‌های مربوط به کانتینرها در دایرکتوری وضعیت ذخیره‌سازی (--runroot)، با این هدف که رکوردهای مربوط به آن‌ها با راه‌اندازی مجدد سیستم حذف شوند. با این حال، همچنان در زمان بالا آمدن سیستم باید جمع‌آوری داده‌های زائد (garbage collection) اضافی انجام شود؛ بنابراین این گزینه باید در بیشتر پیکربندی‌ها غیرفعال باقی بماند. (پیش‌فرض: false)

--userns-gid-map mapping

به طور مستقیم یک نگاشت GID را مشخص می‌کند که باید برای تعیین مالکیت در سطح سیستم فایل، بر روی محتویات کانتینر در حال کار استفاده شود. دستوراتی که هنگام پردازش دستورالعمل‌های RUN اجرا می‌شوند، به طور پیش‌فرض در فضای‌نام کاربری مخصوص به خود که با استفاده از نگاشت‌های UID و GID پیکربندی شده است، اجرا خواهند شد.

مدخل‌های این نگاشت به شکل یک یا چند سه‌تایی جداشده با دونقطه هستند که شامل GID شروع درون کانتینر، GID شروع متناظر در سطح میزبان، و تعداد شناسه‌های متوالی است که مدخل نگاشت نشان می‌دهد.

این گزینه، تنظیم remap-gids در بخش options از /etc/containers/storage.conf را بازنویسی می‌کند.

اگر این گزینه مشخص نشده باشد، اما یک تنظیم سراسری --userns-gid-map ارائه شده باشد، از تنظیمات گزینه سراسری استفاده خواهد شد.

اگر هیچ‌کدام از گزینه‌های --userns-uid-map-user، ‏--userns-gid-map-group یا --userns-gid-map مشخص نشده باشند، اما --userns-uid-map مشخص شده باشد، نگاشت GID طوری تنظیم می‌شود که از همان مقادیر عددی نگاشت UID استفاده کند.

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

--userns-uid-map mapping

به طور مستقیم یک نگاشت UID را مشخص می‌کند که باید برای تعیین مالکیت در سطح سیستم فایل، بر روی محتویات کانتینر در حال کار استفاده شود. دستوراتی که هنگام پردازش دستورالعمل‌های RUN اجرا می‌شوند، به طور پیش‌فرض در فضای‌نام کاربری خود که با استفاده از نگاشت‌های UID و GID پیکربندی شده است، اجرا خواهند شد.

مدخل‌های این نگاشت به شکل یک یا چند سه‌تایی جداشده با دونقطه هستند که شامل UID شروع درون کانتینر، UID شروع متناظر در سطح میزبان، و تعداد شناسه‌های متوالی است که مدخل نگاشت نشان می‌دهد.

این گزینه، تنظیم remap-uids در بخش options از /etc/containers/storage.conf را بازنویسی می‌کند.

اگر این گزینه مشخص نشده باشد، اما یک تنظیم سراسری --userns-uid-map ارائه شده باشد، از تنظیمات گزینه سراسری استفاده خواهد شد.

اگر هیچ‌کدام از گزینه‌های --userns-uid-map-user، ‏--userns-gid-map-group یا --userns-uid-map مشخص نشده باشند، اما --userns-gid-map مشخص شده باشد، نگاشت UID طوری تنظیم می‌شود که از همان مقادیر عددی نگاشت GID استفاده کند.

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

--version, -v

چاپ نسخه برنامه.

Buildah می‌تواند متغیرهای محیطی را از مدخل env در جدول [engine] در containers.conf(5) تنظیم کند. این متغیرها را می‌توان با ارسال متغیرهای محیطی پیش از دستورات buildah بازنویسی کرد.

دستور صفحه راهنما توضیحات
add buildah-add(1) افزودن محتوای یک فایل، نشانی اینترنتی (URL) یا یک دایرکتوری به کانتینر.
build buildah-build(1) ساخت یک ایمیج OCI با استفاده از دستورالعمل‌های موجود در یک یا چند Containerfile.
commit buildah-commit(1) ایجاد یک ایمیج از روی یک کانتینر در حال کار.
config buildah-config(1) به‌روزرسانی تنظیمات پیکربندی ایمیج.
containers buildah-containers(1) فهرست کردن کانتینرهای در حال کار و ایمیج‌های پایه آن‌ها.
copy buildah-copy(1) کپی کردن محتوای یک فایل، نشانی اینترنتی یا دایرکتوری به دایرکتوری کاری کانتینر.
from buildah-from(1) ایجاد یک کانتینر در حال کار جدید، چه از پایه و چه با استفاده از یک ایمیج مشخص به عنوان نقطه آغاز.
images buildah-images(1) فهرست کردن ایمیج‌ها در فضای ذخیره‌سازی محلی.
info buildah-info(1) نمایش اطلاعات سیستم Buildah.
inspect buildah-inspect(1) بازرسی پیکربندی یک کانتینر یا ایمیج.
login buildah-login(1) ورود به یک رجیستری کانتینر.
logout buildah-logout(1) خروج از یک رجیستری کانتینر.
manifest buildah-manifest(1) ایجاد و دستکاری فهرست‌های مانیفست و نمایه‌های ایمیج.
mkcw buildah-mkcw(1) تبدیل یک ایمیج کانتینری معمولی به یک ایمیج بار کاری محرمانه.
mount buildah-mount(1) سوار کردن (mount) سیستم فایل ریشه کانتینر در حال کار.
prune buildah-prune(1) پاکسازی ایمیج‌های واسط و همچنین کش ساخت و سوار کردن.
pull buildah-pull(1) دریافت یک ایمیج از مکان مشخص‌شده.
push buildah-push(1) ارسال یک ایمیج از فضای ذخیره‌سازی محلی به مکانی دیگر.
rename buildah-rename(1) تغییر نام یک کانتینر محلی.
rm buildah-rm(1) حذف یک یا چند کانتینر در حال کار.
rmi buildah-rmi(1) حذف یک یا چند ایمیج.
run buildah-run(1) اجرای یک دستور در داخل کانتینر.
source buildah-source(1) ایجاد، ارسال، دریافت و مدیریت ایمیج‌های منبع و دست‌ساخته‌های منبع مرتبط.
tag buildah-tag(1) افزودن یک نام اضافی به یک ایمیج محلی.
umount buildah-umount(1) پیاده کردن (unmount) سیستم فایل ریشه یک کانتینر در حال کار.
unshare buildah-unshare(1) اجرای یک دستور در یک فضای‌نام کاربری با نگاشت‌های شناسه اصلاح‌شده.
version buildah-version(1) نمایش اطلاعات نسخه Buildah.

storage.conf (/etc/containers/storage.conf)

پرونده storage.conf فایل پیکربندی ذخیره‌سازی برای تمامی ابزارهایی است که از containers/storage استفاده می‌کنند.

فایل پیکربندی ذخیره‌سازی، تمامی گزینه‌های ذخیره‌سازی کانتینری در دسترس را برای ابزارهایی که از فضای ذخیره‌سازی اشتراکی کانتینر بهره می‌برند، مشخص می‌کند.

mounts.conf (/usr/share/containers/mounts.conf و به صورت اختیاری /etc/containers/mounts.conf)

فایل‌های mounts.conf فایل‌ها یا دایرکتوری‌های سوار شدن حجم (volume mount) را مشخص می‌کنند که هنگام اجرای دستورات buildah run یا buildah build به طور خودکار درون کانتینرها سوار می‌شوند. فرایندهای کانتینر می‌توانند از این محتوا استفاده کنند. محتوای حجم سوارشده در ایمیج نهایی ذخیره (commit) نمی‌شود.

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

برای نمونه، در یک mounts.conf با خط «/usr/share/rhel/secrets:/run/secrets»، محتوای دایرکتوری /usr/share/rhel/secrets روی /run/secrets درون کانتینر سوار می‌شود. این نقطه اتصال به اشتراک‌های Red Hat Enterprise Linux میزبان اجازه می‌دهد درون کانتینر استفاده شوند. همچنین اگر مقصد با مسیر مبدأ یکسان باشد، می‌توان از ذکر مقصد صرف‌نظر کرد. به عنوان مثال، مشخص کردن /var/lib/secrets دایرکتوری را در همان مسیر مقصد کانتینر یعنی /var/lib/secrets سوار می‌کند.

توجه داشته باشید که این یک سوار کردن حجم (volume mount) نیست. محتوای این حجم‌ها در فضای ذخیره‌سازی کانتینر کپی می‌شود، نه اینکه مستقیماً از هاست bind mount شود.

registries.conf (/etc/containers/registries.conf)

پرونده registries.conf فایل پیکربندی است که مشخص می‌کند هنگام تکمیل نام ایمیج‌هایی که فاقد بخش رجیستری یا دامنه هستند، به کدام رجیستری‌های کانتینر باید مراجعه شود.

registries.d (/etc/containers/registries.d)

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

containers.conf(5), containers-mounts.conf(5), newuidmap(1), newgidmap(1), containers-registries.conf(5), containers-storage.conf(5)

دسامبر ۲۰۱۷، در ابتدا توسط تام سوینی (Tom Sweeney) گردآوری شد tsweeney@redhat.com ⟨mailto:tsweeney@redhat.com⟩

March 2017 buildah