نام (NAME)

buildah-build - ساخت ایمیج‌های کانتینر با استفاده از دستورالعمل‌های Containerfile یا Dockerfile

خلاصه دستور (SYNOPSIS)

buildah build [گزینه‌ها] [بافت]

buildah bud [گزینه‌ها] [بافت]

توضیحات (DESCRIPTION)

یک ایمیج را با استفاده از دستورالعمل‌های موجود در یک یا چند Containerfile یا Dockerfile و یک دایرکتوری بافت ساخت (build context) مشخص می‌سازد. یک Containerfile از نظر داخلی از نحوی مشابه Dockerfile استفاده می‌کند. در این مستند، فایلی که با عنوان Containerfile نامیده می‌شود می‌تواند فایلی با نام 'Containerfile' یا 'Dockerfile' باشد.

دایرکتوری بافت ساخت می‌تواند به عنوان یک آدرس URL از نوع http(s) مربوط به یک بایگانی (آرشیو)، یک مخزن git یا یک Containerfile مشخص شود.

اگر هیچ دایرکتوری بافتی مشخص نشود، Buildah دایرکتوری کاری فعلی را به عنوان بافت ساخت در نظر می‌گیرد که باید حاوی یک Containerfile باشد.

فایل‌های Containerfile که پسوند ".in" دارند، از طریق cpp(1) پیش‌پردازش خواهند شد. این قابلیت می‌تواند برای تجزیه Containerfileها به چندین بخش قابل استفاده مجدد که از طریق دستورالعمل #include در CPP قابل استفاده هستند، مفید باشد. توجه داشته باشید که فایل Containerfile.in همچنان می‌تواند توسط سایر ابزارها هنگام پیش‌پردازش دستی از طریق cpp -E استفاده شود. هرگونه کامنت (خطوطی که با # شروع می‌شوند) در فایل(های) Containerfile اضافه شده که جزو دستورات پیش‌پردازنده نباشند، در حین ساخت به عنوان هشدار چاپ خواهند شد.

هنگامی که آدرس URL یک بایگانی باشد، محتویات URL در یک مکان موقت دانلود شده و قبل از اجرا استخراج می‌شود.

هنگامی که آدرس URL یک Containerfile باشد، فایل در یک مکان موقت دانلود می‌شود.

هنگامی که یک مخزن Git به عنوان آدرس URL تنظیم می‌شود، مخزن به صورت محلی کلون شده و سپس به عنوان بافت ساخت استفاده می‌شود. می‌توان از یک شاخه غیرپیش‌فرض (یا شناسه کامیت) و زیردایرکتوری از مخزن git کلون‌شده با درج نام آن‌ها در انتهای URL به شکل myrepo.git#mybranch:subdir، myrepo.git#mycommit:subdir، یا در صورتی که زیردایرکتوری باید از شاخه پیش‌فرض استفاده شود به شکل myrepo.git#:subdir استفاده کرد.

گزینه‌ها (OPTIONS)

--add-host=[]

افزودن یک نگاشت سفارشی میزبان به IP (به صورت host:ip)

یک خط به /etc/hosts اضافه می‌کند. قالب آن به صورت hostname:ip است. گزینه --add-host می‌تواند چندین بار مشخص شود. این گزینه با گزینه --no-hosts تداخل دارد.

به جای آدرس IP، می‌توان فلگ ویژه host-gateway را مشخص کرد. این فلگ به یک آدرس IP تبدیل می‌شود که کانتینر می‌تواند از آن برای اتصال به میزبان استفاده کند. آدرس IP انتخاب‌شده به پیکربندی شبکه شما بستگی دارد، بنابراین هیچ تضمینی وجود ندارد که Buildah بتواند آدرس host-gateway را به صورت خودکار تعیین کند، که در این صورت Buildah با پیام خطا متوقف خواهد شد. شما می‌توانید این آدرس IP را با استفاده از گزینه host_containers_internal_ip در containers.conf بازنویسی کنید.

آدرس host-gateway همچنین توسط Buildah برای افزودن خودکار نام‌های میزبان host.containers.internal و host.docker.internal به /etc/hosts استفاده می‌شود. شما می‌توانید با تعیین گزینه --no-hosts یا با تنظیم host_containers_internal_ip="none" در containers.conf از این کار جلوگیری کنید. اگر هیچ آدرس host-gateway به صورت دستی پیکربندی نشده باشد و Buildah نتواند آدرس IP را به طور خودکار تعیین کند، Buildah بدون اعلام خطا از افزودن این نام‌های میزبان داخلی به /etc/hosts صرف‌نظر می‌کند. اگر Buildah درون یک ماشین مجازی با استفاده از podman machine در حال اجرا باشد (این شامل میزبان‌های مک و ویندوز می‌شود)، Buildah از افزودن نام‌های میزبان داخلی به /etc/hosts صرف‌نظر می‌کند، مگر اینکه یک آدرس IP به صورت دستی پیکربندی شده باشد؛ در عوض نام‌های میزبان داخلی توسط حل‌کننده DNS موسوم به gvproxy حل می‌شوند.

برنامه Buildah به طور پیش‌فرض از فایل /etc/hosts میزبان به عنوان پایه استفاده می‌کند، یعنی هر نام میزبانی که در این فایل وجود داشته باشد، در فایل /etc/hosts کانتینر نیز حضور خواهد داشت. یک فایل پایه متفاوت می‌تواند با استفاده از پیکربندی base_hosts_file در containers.conf تنظیم شود.

--all-platforms

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

--annotation annotation[=value]

یک یادداشت ایمیج (annotation) (مانند annotation=value) را به فراداده ایمیج اضافه می‌کند. می‌تواند چندین بار استفاده شود. اگر annotation نام‌گذاری شود اما نه = و نه یک value ارائه نشود، آنگاه annotation روی یک مقدار خالی تنظیم می‌شود.

نکته: این اطلاعات در قالب‌های ایمیج Docker وجود ندارد، بنابراین هنگام نوشتن ایمیج‌ها در قالب‌های Docker نادیده گرفته می‌شود.

--arch="ARCH"

معماری (ARCH) ایمیجی که باید ساخته شود و معماری ایمیج پایه‌ای که باید دریافت (pull) شود (در صورتی که ساخت از آن استفاده کند) را به مقدار ارائه‌شده تنظیم می‌کند، به جای اینکه از معماری میزبان استفاده شود. (مثال‌ها: arm، arm64، 386، amd64، ppc64le، s390x)

--authfile path

مسیر فایل احراز هویت. پیش‌فرض ${XDG_RUNTIME_DIR}/containers/auth.json است. برای اطلاعات بیشتر containers-auth.json(5) را ببینید. این فایل با استفاده از buildah login ایجاد می‌شود.

اگر وضعیت احراز هویت در آنجا یافت نشود، $HOME/.docker/config.json بررسی می‌شود که با استفاده از docker login تنظیم شده است.

نکته: شما همچنین می‌توانید مسیر پیش‌فرض فایل احراز هویت را با تنظیم متغیر محیطی REGISTRY_AUTH_FILE لغو و بازنویسی کنید. export REGISTRY_AUTH_FILE=path

--build-arg arg=value

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

لطفاً برای مشاهده فهرست متغیرهایی که می‌توانند در زمان اجرا درون Containerfile بازنویسی شوند، به بخش متغیرهای زمان ساخت (BUILD TIME VARIABLES) ⟨#build-time-variables⟩ مراجعه کنید.

--build-arg-file path

فایلی حاوی خطوطی از آرگومان‌های ساخت به فرم arg=value را مشخص می‌کند. نام فایل پیشنهادی argfile.conf است.

خطوط توضیحات (کامنت) که با # شروع می‌شوند، به همراه خطوط خالی نادیده گرفته می‌شوند. سایر خطوط باید در قالب arg=value باشند که به --build-arg داده می‌شود.

اگر چندین آرگومان از طریق گزینه‌های --build-arg-file و --build-arg ارائه شوند، آرگومان‌های ساخت بین تمامی فایل‌های ارائه‌شده و آرگومان‌های خط فرمان ادغام خواهند شد.

هر فایلی که در گزینه --build-arg-file مشخص شود، قبل از آرگومان‌های ارائه‌شده از طریق گزینه --build-arg خوانده خواهد شد.

هنگامی که یک نام آرگومان مشخص چندین بار تعیین شود، آخرین نمونه همان مقداری است که به فرآیند ساخت نهایی ارسال می‌شود. این بدان معناست که مقادیر --build-arg همیشه مقادیر موجود در --build-arg-file را بازنویسی و باطل می‌کنند.

--build-context name=value

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

مقادیر معتبر می‌توانند موارد زیر باشند: * دایرکتوری محلی – برای مثال --build-context project2=../path/to/project2/src * آدرس اینترنتی HTTP به یک tarball – برای مثال --build-context src=https://example.org/releases/src.tar * ایمیج کانتینر – مشخص‌شده با پیشوند container-image://، برای مثال --build-context alpine=container-image://alpine:3.15 (همچنین docker:// و docker-image:// را نیز می‌پذیرد)

در سمت Containerfile، می‌توانید در تمامی دستوراتی که پارامتر «from» را می‌پذیرند به این بافت ساخت ارجاع دهید. نمونه نحوه استفاده به این صورت است:

FROM [name]
COPY --from=[name] ...
RUN --mount=from=[name] …

مقدار [name] با اولویت زیر مطابقت داده می‌شود:

--cache-from

مخزنی که به عنوان فهرست احتمالی منابع کش استفاده می‌شود. هنگامی که مشخص شود، Buildah تلاش خواهد کرد تا ایمیج‌های کش را در مخازن مشخص‌شده جستجو کند و به جای اجرای واقعی مراحل ساخت به صورت محلی، اقدام به دریافت (pull) ایمیج‌های کش خواهد کرد. Buildah تنها زمانی برای دریافت ایمیج‌های کش‌شده قبلی تلاش می‌کند که آن‌ها به عنوان تطابق‌های معتبر کش (cache hits) در نظر گرفته شوند.

از گزینه --cache-to برای پر کردن یک یا چند مخزن راه دور با محتوای کش استفاده کنید.

مثال

# populate a cache and also consult it
buildah build -t test --layers --cache-to registry/myrepo/cache --cache-from registry/myrepo/cache .

نکته: گزینه --cache-from نادیده گرفته می‌شود مگر اینکه --layers مشخص شده باشد.

نکته: گزینه --cache-from در Buildah متفاوت از گزینه --cache-from در Docker و BuildKit طراحی شده است. مکانیزم کش توزیع‌شده در Buildah ایمیج‌های میانی را مستقیماً از خود رجیستری راه دور دریافت می‌کند، بر خلاف Docker و BuildKit که ایمیج میانی درون خود ایمیج ذخیره می‌شود. رویکرد Buildah مشابه kaniko است که اندازه ایمیج اصلی را با ایمیج‌های میانی افزایش نمی‌دهد. همچنین با استفاده از مکانیزم کش Buildah، ایمیج‌های میانی واقعاً می‌توانند به صورت توزیع‌شده در یک یا چند رجیستری راه دور نگهداری شوند.

--cache-to

این فلگ را برای مشخص کردن فهرستی از مخازن راه دور که برای ذخیره ایمیج‌های کش استفاده می‌شوند تنظیم کنید. Buildah تلاش خواهد کرد تا ایمیج کش تازه‌ساخته‌شده را به مخازن راه دور ارسال (push) کند.

نکته: به منظور استفاده از محتوای کش در یک مخزن راه دور، از گزینه --cache-from استفاده کنید.

مثال

# populate a cache and also consult it
buildah build -t test --layers --cache-to registry/myrepo/cache --cache-from registry/myrepo/cache .

نکته: گزینه --cache-to نادیده گرفته می‌شود مگر اینکه --layers مشخص شده باشد.

نکته: گزینه --cache-to در Buildah متفاوت از گزینه --cache-to در Docker و BuildKit طراحی شده است. مکانیزم کش توزیع‌شده در Buildah ایمیج‌های میانی را مستقیماً به خود رجیستری راه دور ارسال می‌کند، بر خلاف Docker و BuildKit که ایمیج میانی درون خود ایمیج ذخیره می‌شود. رویکرد Buildah مشابه kaniko است که اندازه ایمیج اصلی را با ایمیج‌های میانی افزایش نمی‌دهد. همچنین با استفاده از مکانیزم کش Buildah، ایمیج‌های میانی واقعاً می‌توانند به صورت توزیع‌شده در یک یا چند رجیستری راه دور نگهداری شوند.

--cache-ttl duration

استفاده از ایمیج‌های کش‌شده را تنها به ایمیج‌هایی محدود می‌کند که برچسب زمانی ایجاد آن‌ها کمتر از duration پیش باشد. برای مثال اگر --cache-ttl=1h مشخص شود، Buildah تنها ایمیج‌های کش میانی را در نظر می‌گیرد که در بازه زمانی کمتر از یک ساعت ایجاد شده باشند، و ایمیج‌های کش میانی خارج از این بازه زمانی نادیده گرفته خواهند شد.

نکته: تنظیم دستی --cache-ttl=0 در پیاده‌سازی معادل استفاده از --no-cache است، زیرا عملاً به این معنی است که کاربر به هیچ وجه مایل به استفاده از کش نیست. --cap-add=CAP_xxx

هنگام اجرای دستورالعمل‌های RUN، دستور مشخص‌شده در دستورالعمل را با قابلیت (capability) مشخص‌شده که به مجموعه قابلیت‌های آن اضافه شده است، اجرا می‌کند. برخی از قابلیت‌ها به صورت پیش‌فرض اعطا می‌شوند؛ این گزینه می‌تواند برای افزودن قابلیت‌های بیشتر استفاده شود.

--cap-drop=CAP_xxx

هنگام اجرای دستورالعمل‌های RUN، دستور مشخص‌شده در دستورالعمل را در حالی اجرا می‌کند که قابلیت مشخص‌شده از مجموعه قابلیت‌های آن حذف شده است. قابلیت‌های CAP_CHOWN، CAP_DAC_OVERRIDE، CAP_FOWNER، CAP_FSETID، CAP_KILL، CAP_NET_BIND_SERVICE، CAP_SETFCAP، CAP_SETGID، CAP_SETPCAP و CAP_SETUID به‌طور پیش‌فرض اعطا می‌شوند؛ این گزینه می‌تواند برای حذف آن‌ها استفاده شود. فهرست قابلیت‌های پیش‌فرض در containers.conf(5) مدیریت می‌شود.

اگر یک قابلیت هم برای گزینه --cap-add و هم برای گزینه --cap-drop مشخص شود، صرف‌نظر از ترتیبی که گزینه‌ها مشخص شده‌اند، حذف خواهد شد.

--cert-dir path

از گواهی‌های موجود در path (*.crt، *.cert، *.key) برای اتصال به رجیستری و بازیابی محتوا از مکان‌های HTTPS برای دستورالعمل‌های ADD استفاده می‌کند. دایرکتوری پیش‌فرض گواهی‌ها /etc/containers/certs.d است.

--cgroup-parent=""

مسیر cgroups که cgroup مربوط به دستورالعمل‌های RUN در زیر آن ایجاد خواهد شد. اگر مسیر مطلق نباشد، مسیر نسبت به مسیر cgroups فرایند init در نظر گرفته می‌شود. اگر cgroupها از قبل وجود نداشته باشند، ایجاد خواهند شد.

--cgroupns how

پیکربندی فضاهای نام cgroup (cgroup namespaces) را هنگام پردازش دستورالعمل‌های RUN تنظیم می‌کند. مقدار پیکربندی‌شده می‌تواند "" (رشته خالی) یا "private" باشد که نشان می‌دهد باید یک فضای نام cgroup جدید ایجاد شود، یا می‌تواند "host" باشد که نشان می‌دهد باید از فضای نام cgroup که خود buildah در آن اجرا می‌شود مجدداً استفاده شود.

--compat-volumes

دایرکتوری‌هایی را که با استفاده از دستورالعمل VOLUME علامت‌گذاری شده‌اند (چه در این بیلد و چه مواردی که از تصاویر پایه به ارث رسیده‌اند) به گونه‌ای مدیریت می‌کند که محتوای آن‌ها فقط توسط دستورالعمل‌های ADD و COPY قابل تغییر باشد. هر تغییری که توسط دستورالعمل‌های RUN در آن مکان‌ها ایجاد شود بازگردانده (revert) خواهد شد. قبل از معرفی این گزینه، این رفتار به صورت پیش‌فرض فعال بود، اما اکنون به صورت پیش‌فرض غیرفعال است.

--compress

این گزینه برای همگامی با سایر رابط‌های خط فرمان (CLI) کانتینرها اضافه شده است. ابزار Buildah کپی‌ای از دایرکتوری زمینه (context directory) را به یک دیمن یا کارساز راه دور ارسال نمی‌کند. بنابراین، فشرده‌سازی داده‌ها قبل از ارسال برای Buildah بی‌مورد و نامربوط است.

--compression-format format

قالب فشرده‌سازی مورد استفاده را مشخص می‌کند. مقادیر پشتیبانی‌شده عبارتند از: gzip، zstd و zstd:chunked. مقدار zstd:chunked با رمزگذاری تصاویر ناسازگار است و در این حالت همراه با یک هشدار به صورت zstd رفتار خواهد شد. اگر مشخص نشود، قالب از تنظیمات compression_format در containers.conf خوانده می‌شود.

این گزینه بر ارسال حافظه نهان با --cache-to و تصویر نهایی هنگام نوشتن در یک مقصد غیرمحلی (مانند dir:، oci:، oci-archive: یا یک رجیستری) تأثیر می‌گذارد. هنگامی که خروجی، ذخیره‌سازی کانتینر محلی باشد (حالت پیش‌فرض)، لایه‌ها همیشه هنگام ورود از حالت فشرده خارج می‌شوند، بنابراین فشرده‌سازی در زمان buildah push اعمال می‌شود.

--compression-level level

سطح فشرده‌سازی مورد استفاده را مشخص می‌کند. این مقدار بستگی به الگوریتم فشرده‌سازی مورد استفاده دارد؛ به عنوان مثال برای zstd مقادیر پذیرفته‌شده در محدوده ۱-۲۰ (شامل خود این اعداد) است، در حالی که برای gzip بین ۱-۹ (شامل خود این اعداد) می‌باشد. اگر مشخص نشود، سطح فشرده‌سازی از تنظیمات compression_level در containers.conf خوانده می‌شود.

--cpp-flag=""

تنظیم فلگ‌های اضافی برای ارسال به پیش‌پردازنده سی cpp(1). پرونده‌های Containerfile که با پسوند ".in" پایان می‌یابند از طریق cpp(1) پیش‌پردازش می‌شوند. این گزینه می‌تواند برای ارسال فلگ‌های اضافی به cpp استفاده شود. نکته: شما همچنین می‌توانید با تنظیم متغیر محیطی BUILDAH_CPPFLAGS، مقادیر پیش‌فرض CPPFLAGS را تنظیم کنید (مانند export BUILDAH_CPPFLAGS="-DDEBUG").

--cpu-period=0

دوره CPU را برای زمان‌بند کاملاً منصفانه (CFS) که مدت زمانی بر حسب میکروثانیه است تنظیم می‌کند. هنگامی که سهمیه (quota) پردازنده کانتینر مصرف شود، تا زمانی که دوره جاری به پایان نرسد، کانتینر برای اجرا زمان‌بندی نخواهد شد. مقدار پیش‌فرض ۱۰۰۰۰۰ میکروثانیه است.

در برخی سیستم‌ها، ممکن است تغییر محدودیت‌های پردازنده برای کاربران غیر ریشه (non-root) مجاز نباشد. برای اطلاعات بیشتر، ببینید: https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error

--cpu-quota=0

محدود کردن سهمیه (quota) پردازنده برای CFS (زمان‌بند کاملاً منصفانه)

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

در برخی سیستم‌ها، ممکن است تغییر محدودیت‌های پردازنده برای کاربران غیر ریشه (non-root) مجاز نباشد. برای اطلاعات بیشتر، ببینید: https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error

--cpu-shares, -c=0

سهم‌های پردازنده (وزن نسبی)

به‌طور پیش‌فرض، همه کانتینرها سهم یکسانی از چرخه‌های پردازنده دریافت می‌کنند. این نسبت می‌تواند با تغییر وزن سهم پردازنده کانتینر نسبت به وزن سایر کانتینرهای در حال اجرا تغییر یابد.

برای تغییر این نسبت از مقدار پیش‌فرض ۱۰۲۴، از فلگ --cpu-shares برای تنظیم وزن روی ۲ یا بالاتر استفاده کنید.

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

به عنوان مثال، سه کانتینر را در نظر بگیرید که یکی دارای cpu-share با مقدار ۱۰۲۴ و دو کانتینر دیگر دارای cpu-share با مقدار ۵۱۲ هستند. هنگامی که فرایندها در هر سه کانتینر تلاش کنند ۱۰۰٪ پردازنده را استفاده نمایند، کانتینر اول ۵۰٪ از کل زمان پردازنده را دریافت خواهد کرد. اگر کانتینر چهارمی با cpu-share برابر با ۱۰۲۴ اضافه کنید، کانتینر اول فقط ۳۳٪ از پردازنده را دریافت می‌کند. کانتینرهای باقی‌مانده به ترتیب ۱۶.۵٪، ۱۶.۵٪ و ۳۳٪ از پردازنده را دریافت خواهند کرد.

در یک سیستم چند‌هسته‌ای، سهم‌های زمان پردازنده در تمام هسته‌های پردازنده توزیع می‌شوند. حتی اگر یک کانتینر به کمتر از ۱۰۰٪ کل زمان پردازنده محدود شده باشد، می‌تواند از ۱۰۰٪ هر یک از هسته‌های اختصاصی پردازنده استفاده کند.

برای مثال، سیستمی با بیش از سه هسته را در نظر بگیرید. اگر یک کانتینر {C0} با -c=512 در حال اجرای یک فرایند را راه‌اندازی کنید، و کانتینر دیگری {C1} با -c=1024 در حال اجرای دو فرایند باشد، می‌تواند به تقسیم سهم‌های پردازنده به شکل زیر منجر شود:

PID    container	CPU	CPU share
100    {C0}		0	100% of CPU0
101    {C1}		1	100% of CPU1
102    {C1}		2	100% of CPU2

--cpuset-cpus=""

پردازنده‌هایی که اجازه اجرا در آن‌ها داده می‌شود (0-3, 0,1)

--cpuset-mems=""

گره‌های حافظه (MEMs) که اجازه اجرا در آن‌ها داده می‌شود (0-3, 0,1). فقط در سیستم‌های NUMA مؤثر است.

اگر چهار گره حافظه در سیستم خود دارید (0-3)، با استفاده از --cpuset-mems=0,1 فرایندهای موجود در کانتینر شما فقط از حافظه دو گره اول حافظه استفاده خواهند کرد.

--created-annotation

یک یادداشت (annotation) تصویر (همچنین ببینید: --annotation) به فراداده (متادیتا) تصویر اضافه می‌کند که مقدار "org.opencontainers.image.created" را روی زمان فعلی، یا روی برچسب زمانی مشخص‌شده با فلگ --source-date-epoch یا --timestamp (در صورت استفاده از هرکدام) تنظیم می‌کند. اگر مقدار false باشد، چنین یادداشتی در تصویر نوشته‌شده وجود نخواهد داشت.

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

--creds creds

مقدار [username[:password]] برای استفاده جهت احراز هویت با رجیستری در صورت نیاز. اگر یک یا هر دو مقدار ارائه نشوند، یک اعلان خط فرمان ظاهر می‌شود و می‌توان مقدار را وارد کرد. گذرواژه بدون نمایش (echo) وارد می‌شود.

--cw options

تولید تصویری مناسب برای استفاده به عنوان بار کاری محرمانه (confidential workload) در حال اجرا در یک محیط اجرای معتمد (TEE) با استفاده از krun (یعنی crun ساخته‌شده با ویژگی فعال libkrun که به عنوان krun فراخوانی می‌شود). به جای محتویات معمول، سامانه پرونده ریشه (rootfs) تصویر شامل یک تصویر دیسک رمزگذاری‌شده و اطلاعات پیکربندی برای krun خواهد بود.

مقدار options یک فهرست جداشده با کاما از جفت‌های key=value است که اطلاعات پیکربندی لازم برای تولید داده‌های اضافی را که در تصویر کانتینر گنجانده می‌شوند، فراهم می‌کند.

کلیدهای (keys) شناخته‌شده عبارتند از:

attestation_url: محل کارساز تصدیق / کارگزار کلید (key broker / attestation server). اگر مقداری مشخص شود، شناسه بار کاری تصویر جدید به همراه عبارت عبور استفاده‌شده برای رمزگذاری تصویر دیسک در کارساز ثبت خواهد شد و محل کارساز در تصویر کانتینر ذخیره می‌شود. در زمان اجرا، انتظار می‌رود krun با کارساز تماس گرفته و با استفاده از شناسه بار کاری که در تصویر کانتینر نیز ذخیره شده است، عبارت عبور را بازیابی کند. اگر مقداری مشخص نشود، مقدار passphrase باید مشخص گردد.

cpus: تعداد پردازنده‌های مجازی (vCPU) که تصویر انتظار دارد در زمان اجرا با آن اجرا شود. اگر مشخص نشود، یک مقدار پیش‌فرض ارائه خواهد شد.

firmware_library: محل کتابخانه مشترک libkrunfw-sev. اگر مشخص نشود، buildah وجود آن را در چندین مکان ثابت بررسی می‌کند.

memory: مقدار حافظه‌ای که تصویر انتظار دارد در زمان اجرا با آن اجرا شود، بر حسب مگابایت. اگر مشخص نشود، یک مقدار پیش‌فرض ارائه خواهد شد.

passphrase: عبارت عبور مورد استفاده برای رمزگذاری تصویر دیسک که درون تصویر کانتینر گنجانده خواهد شد. اگر مقداری مشخص نشود، اما مقدار attestation_url مشخص شده باشد، یک عبارت عبور تصادفی تولید و استفاده خواهد شد. نویسندگان توصیه می‌کنند مقدار attestation_url تنظیم شود اما passphrase تنظیم نگردد.

slop: فضای اضافی برای تخصیص به تصویر دیسک در مقایسه با اندازه محتویات تصویر کانتینر، که یا به صورت درصد (..%) یا به صورت مقدار اندازه (بایت، یا واحدهای بزرگ‌تر در صورت وجود پسوندهایی مانند KB یا MB) یا مجموع دو یا چند مورد از این مشخصات بیان می‌شود. اگر مشخص نشود، buildah حدس می‌زند که ۲۵٪ فضای بیشتر نسبت به محتویات کافی خواهد بود، اما این گزینه برای مواقعی که حدس آن نادرست باشد ارائه شده است.

type: نوع محیط اجرای معتمد (TEE) که تصویر باید برای استفاده با آن علامت‌گذاری شود. مقادیر پذیرفته‌شده عبارتند از "SEV" (مجازی‌سازی رمزگذاری‌شده امن AMD - وضعیت رمزگذاری‌شده) و "SNP" (مجازی‌سازی رمزگذاری‌شده امن AMD - صفحه‌بندی تودرتوی امن). در صورت عدم تعیین، پیش‌فرض "SNP" است.

workload_id: یک شناسه بار کاری که در تصویر کانتینر ثبت خواهد شد تا در زمان اجرا برای بازیابی عبارت عبوری که برای رمزگذاری تصویر دیسک استفاده شده بود، به کار رود. اگر مشخص نشود، یک مقدار نیمه‌تصادفی از شناسه تصویرِ تصویر پایه به دست خواهد آمد.

--decryption-key key[:passphrase]

مقدار [key[:passphrase]] برای رمزگشایی تصاویر استفاده می‌شود. کلید می‌تواند به کلیدها و/یا گواهی‌ها اشاره کند. رمزگشایی با تمام کلیدها امتحان خواهد شد. اگر کلید با عبارت عبور محافظت شده باشد، لازم است در آرگومان ارسال شود و در غیر این صورت حذف شود.

--device=device

یک دستگاه میزبان یا دستگاه‌های زیر یک دایرکتوری را به محیط هر دستورالعمل RUN که در طول بیلد اجرا می‌شود اضافه می‌کند. پارامتر اختیاری permissions می‌تواند برای تعیین مجوزهای دستگاه با استفاده از یک یا چند مورد از r برای خواندن، w برای نوشتن و m برای mknod(2) استفاده شود.

مثال: --device=/dev/sdc:/dev/xvdc:rwm.

نکته: اگر host-device یک پیوند نمادین (symbolic link) باشد، ابتدا حل‌وفصل می‌شود. کانتینر فقط شماره‌های اصلی و فرعی (major and minor numbers) دستگاه میزبان را ذخیره خواهد کرد.

دستگاه مورد نظر برای اشتراک‌گذاری می‌تواند با استفاده از مشخصات واسط دستگاه کانتینر (CDI) نیز تعیین شود (https://github.com/cncf-tags/container-device-interface).

نکته: اگر کاربر فقط از طریق یک گروه دارای حقوق دسترسی باشد، دسترسی به دستگاه از داخل یک کانتینر بدون ریشه (rootless) با شکست مواجه خواهد شد. زمان اجرای crun(1) با افزودن گزینه --annotation run.oci.keep_original_groups=1 راهکاری را برای این مورد ارائه می‌دهد. --disable-compression، -D

لایه‌های سیستم‌فایل هنگام ساخت تصویر فشرده‌سازی نمی‌شوند مگر اینکه مکانی که تصویر در آن نوشته می‌شود به آن نیاز داشته باشد. این تنظیم پیش‌فرض است، زیرا لایه‌های تصویر هنگام ارسال (push) به رجیستری‌ها به‌طور خودکار فشرده می‌شوند و تصاویری که در فضای ذخیره‌سازی محلی نوشته می‌شوند تنها برای ذخیره‌شدن باید دوباره از حالت فشرده خارج شوند. فشرده‌سازی می‌تواند در تمام موارد با تعیین --disable-compression=false اجبار شود.

--disable-content-trust

این یک گزینه مخصوص داکر برای غیرفعال کردن اعتبارسنجی تصویر در یک رجیستری کانتینر است و توسط Buildah پشتیبانی نمی‌شود. این فلگ یک دستور بی‌اثر (NOOP) است و صرفاً برای سازگاری اسکریپت‌ها ارائه شده است.

--dns=[]

تنظیم سرورهای DNS سفارشی. استفاده از --dns همراه با --network=none نامعتبر است.

این گزینه می‌تواند برای بازنویسی پیکربندی DNS ارائه‌شده به کانتینر استفاده شود. معمولاً زمانی این کار لازم است که پیکربندی DNS میزبان برای کانتینر نامعتبر باشد (برای نمونه 127.0.0.1). در این حالت، فلگ --dns برای هر بار اجرا ضروری است.

مقدار ویژه none می‌تواند برای غیرفعال کردن ایجاد /etc/resolv.conf در کانتینر توسط Buildah تعیین شود. فایل /etc/resolv.conf موجود در تصویر بدون تغییر استفاده خواهد شد.

--dns-option=[]

تنظیم گزینه‌های DNS سفارشی. استفاده از --dns-option همراه با --network=none نامعتبر است.

--dns-search=[]

تنظیم دامنه‌های جستجوی DNS سفارشی. استفاده از --dns-search همراه با --network=none نامعتبر است.

--env env[=value]

افزودن یک مقدار (برای نمونه env=value) به تصویر ساخته‌شده. این گزینه می‌تواند چندین بار استفاده شود. اگر نه = و نه یک *value* تعیین نشده باشد، اما env در محیط فعلی تنظیم شده باشد، مقدار از محیط فعلی به تصویر اضافه خواهد شد. مقدار env می‌تواند توسط دستورالعمل‌های ENV در Containerfile بازنویسی شود. برای حذف یک متغیر محیطی از تصویر ساخته‌شده، از گزینه --unsetenv استفاده کنید.

--file، -f Containerfile

یک Containerfile را مشخص می‌کند که حاوی دستورالعمل‌هایی برای ساخت تصویر است؛ چه یک فایل محلی باشد یا یک URL با پروتکل http یا https. اگر بیش از یک Containerfile تعیین شده باشد، دستورالعمل‌های FROM تنها از آخرین فایل مشخص‌شده پذیرفته خواهند شد.

اگر یک فایل محلی به عنوان Containerfile مشخص شده باشد و وجود نداشته باشد، دایرکتوری زمینه (context directory) به ابتدای مقدار فایل محلی اضافه خواهد شد.

اگر -f - را مشخص کنید، محتویات Containerfile از ورودی استاندارد (stdin) خوانده خواهد شد.

--force-compression

در صورت تنظیم، از الگوریتم فشرده‌سازی مشخص‌شده استفاده می‌کند حتی اگر مقصد از قبل حاوی نسخه‌ای با فشرده‌سازی متفاوت باشد. اگر --compression-format به‌طور صریح در خط فرمان مشخص شده باشد یا compression_format در containers.conf تنظیم شده باشد، مقدار پیش‌فرض true است، در غیر این صورت false می‌باشد.

--force-rm bool-value

همیشه کانتینرهای میانی را پس از ساخت حذف می‌کند، حتی اگر ساخت با شکست مواجه شود (پیش‌فرض false است).

--format

قالب مانیفست و داده‌های پیکربندی تصویر ساخته‌شده را کنترل می‌کند. قالب‌های شناخته‌شده شامل oci (مشخصات OCI image-spec v1.0، پیش‌فرض) و docker (نسخه 2، با استفاده از قالب شِمای 2 برای مانیفست) هستند.

نکته: همچنین می‌توانید قالب پیش‌فرض را با تنظیم متغیر محیطی BUILDAH_FORMAT بازنویسی کنید. export BUILDAH_FORMAT=docker

--from

نخستین دستورالعمل FROM را درون Containerfile بازنویسی می‌کند. اگر چندین دستورالعمل FROM در یک Containerfile وجود داشته باشد، تنها دستورالعمل اول تغییر می‌کند.

--group-add=group | keep-groups

اختصاص گروه‌های اضافی به کاربر اصلی در حال اجرا درون فرایند کانتینر.

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

--help، -h

چاپ راهنمای نحوه استفاده (usage statement)

--hooks-dir path

هر فایل *.json در مسیر، یک قلاب (hook) را برای کانتینرهای ساخت buildah پیکربندی می‌کند. برای جزئیات بیشتر در مورد ساختار فایل‌های JSON و معناشناسی تزریق قلاب، به oci-hooks(5) مراجعه کنید. ابزار Buildah در حال حاضر از هر دو شِمای قلاب 1.0.0 و 0.1.0 پشتیبانی می‌کند، هرچند شِمای 0.1.0 منسوخ شده است.

این گزینه ممکن است چندین بار تنظیم شود؛ مسیرهای مربوط به گزینه‌های بعدی دارای اولویت بالاتری هستند (صفحه راهنمای oci-hooks(5) اولویت دایرکتوری را مورد بحث قرار می‌دهد).

برای شرایط حاشیه‌نویسی (annotation conditions)،‏ buildah از هرگونه حاشیه‌نویسی تنظیم‌شده در پیکربندی OCI ایجادشده استفاده می‌کند.

برای شرایط متصل‌کردن پیوندی (bind-mount conditions)، تنها اتصال‌هایی که به‌طور صریح توسط فراخواننده از طریق --volume درخواست شده‌اند در نظر گرفته می‌شوند. اتصال‌های پیوندی که buildah به‌طور پیش‌فرض درج می‌کند (مانند /dev/shm) در نظر گرفته نمی‌شوند.

اگر --hooks-dir برای فراخوانندگان ریشه (root) تنظیم نشده باشد، Buildah در حال حاضر به ترتیب افزایش اولویت به /usr/share/containers/oci/hooks.d و /etc/containers/oci/hooks.d پیش‌فرض خواهد بود. استفاده از این مقادیر پیش‌فرض منسوخ شده است و فراخوانندگان باید به تنظیم صریح --hooks-dir مهاجرت کنند.

--http-proxy=true

به‌طور پیش‌فرض، اگر متغیرهای محیطی پروکسی برای فرایند buildah تنظیم شده باشند، به داخل کانتینر منتقل می‌شوند. این رفتار را می‌توان با تنظیم گزینه --http-proxy روی false غیرفعال کرد. متغیرهای محیطی منتقل‌شده شامل http_proxy،‏ https_proxy،‏ ftp_proxy،‏ no_proxy و همچنین نسخه‌های با حروف بزرگ آن‌ها هستند.

--identity-label bool-value

یک برچسب io.buildah.version اضافه می‌کند که مقدار آن برابر با نسخه buildah که تصویر را ساخته است تنظیم می‌شود (پیش‌فرض true است مگر اینکه از --timestamp یا --source-date-epoch استفاده شود).

--ignorefile file

مسیر به یک فایل .containerignore (.dockerignore) جایگزین.

--iidfile ImageIDfile

شناسه تصویر ساخته‌شده را در فایل می‌نویسد. هنگامی که --platform بیش از یک بار مشخص شده باشد، تلاش برای استفاده از این گزینه خطایی را ایجاد خواهد کرد.

--iidfile-raw ImageIDfile

شناسه تصویر ساخته‌شده را بدون پیشوند الگوریتم (برای نمونه sha256:) در فایل می‌نویسد. هنگامی که --platform بیش از یک بار مشخص شده باشد، تلاش برای استفاده از این گزینه خطایی را ایجاد خواهد کرد.

نام مستعار --raw-iidfile نیز در دسترس است.

--inherit-annotations bool-value

حاشیه‌نویسی‌ها (annotations) را از تصویر پایه یا مراحل پایه به ارث می‌برد (پیش‌فرض true است). موارد استفاده‌ای که این فلگ را روی false تنظیم می‌کنند ممکن است نیاز داشته باشند همین کار را برای فلگ --created-annotation نیز انجام دهند.

--inherit-labels bool-value

برچسب‌ها (labels) را از تصویر پایه یا مراحل پایه به ارث می‌برد (پیش‌فرض true است).

--ipc how

پیکربندی فضاهای نام IPC را هنگام رسیدگی به دستورالعمل‌های RUN تنظیم می‌کند. مقدار پیکربندی‌شده می‌تواند "" (رشته خالی) یا "container" برای نشان دادن اینکه یک فضای نام IPC جدید باید ایجاد شود، یا "host" برای نشان دادن اینکه فضای نام IPC که خود buildah در آن در حال اجرا است باید مجدداً استفاده شود، یا مسیر یک فضای نام IPC که از قبل توسط فرایند دیگری در حال استفاده است، باشد.

--isolation type

نوع ایزوله‌سازی مورد استفاده برای اجرای فرایندها به عنوان بخشی از دستورالعمل‌های RUN را کنترل می‌کند. انواع شناخته‌شده شامل oci (زمان اجرای سازگار با OCI، پیش‌فرض)، rootless (زمان اجرای سازگار با OCI که با استفاده از پیکربندی اصلاح‌شده فراخوانی می‌شود، همراه با --no-new-keyring اضافه‌شده به فراخوانی create آن، با استفاده مجدد از فضاهای نام شبکه و UTS میزبان، و ایجاد فضاهای نام خصوصی IPC،‏ PID، متصل‌کردن (mount) و کاربر؛ پیش‌فرض برای کاربران بدون امتیاز)، و chroot (یک پوشش‌دهنده داخلی که بیشتر به chroot(1) تمایل دارد تا فناوری کانتینر، با استفاده مجدد از فضاهای نام گروه کنترلی (cgroup)، شبکه، IPC و PID میزبان، و ایجاد فضاهای نام خصوصی mount و UTS، و ایجاد فضاهای نام کاربر تنها زمانی که برای نگاشت شناسه مورد نیاز باشند) هستند.

نکته: همچنین می‌توانید نوع ایزوله‌سازی پیش‌فرض را با تنظیم متغیر محیطی BUILDAH_ISOLATION بازنویسی کنید. export BUILDAH_ISOLATION=oci

--jobs N

حداکثر N مرحله همزمان را به صورت موازی اجرا می‌کند. اگر تعداد کارها بیشتر از 1 باشد، stdin از /dev/null خوانده خواهد شد. اگر 0 مشخص شود، هیچ محدودیتی برای تعداد کارهایی که به صورت موازی اجرا می‌شوند وجود نخواهد داشت.

--label label[=value]

افزودن یک برچسب تصویر label (برای نمونه label=value) به متاداده تصویر. این گزینه می‌تواند چندین بار استفاده شود. اگر نام label ذکر شود، اما نه = و نه یک value ارائه نشود، آنگاه label روی یک مقدار خالی تنظیم می‌شود.

کاربران می‌توانند یک LABEL ویژه به صورت io.containers.capabilities=CAP1,CAP2,CAP3 در یک Containerfile تنظیم کنند که فهرست قابلیت‌های (capabilities) لینوکس مورد نیاز برای اجرای درست کانتینر را مشخص می‌کند. این برچسب تعیین‌شده در تصویر کانتینر به موتورهای کانتینر، مانند Podman، که این برچسب را می‌شناسند می‌گوید تا کانتینر را فقط با همین قابلیت‌ها اجرا کنند. موتور کانتینر کانتینر را فقط با قابلیت‌های مشخص‌شده راه‌اندازی می‌کند، تا زمانی که این فهرست از قابلیت‌ها زیرمجموعه‌ای از فهرست پیش‌فرض باشد.

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

--layer-label label[=value]

افزودن یک برچسب تصویر میانی label (برای نمونه label=value) به متاداده در تصاویر میانی، یعنی هر تصویری که برای مراحل غیرنهایی و برای دستورالعمل‌های غیرنهایی در مراحلی که --layers برابر با true است ساخته شده باشد. این گزینه می‌تواند چندین بار استفاده شود. اگر نام label ذکر شود، اما نه = و نه یک value ارائه نشود، آنگاه label روی یک مقدار خالی تنظیم می‌شود.

--layers bool-value

کش‌کردن تصاویر میانی در طول فرایند ساخت (پیش‌فرض false است).

نکته: همچنین می‌توانید مقدار پیش‌فرض لایه‌ها را با تنظیم متغیر محیطی BUILDAH_LAYERS بازنویسی کنید. export BUILDAH_LAYERS=true

--logfile filename

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

--logsplit bool-value

در صورت مشخص شدن --logfile و --platform، این فلگ به کاربران نهایی اجازه می‌دهد تا فایل لاگ را برای هر پلتفرم در فایل‌های جداگانه‌ای با الگوی نام‌گذاری ${logfile}_${platform-os}_${platform-arch} تقسیم کنند.

--manifest listName

نام لیست مانیفستی که ایمیج ساخته‌شده به آن اضافه خواهد شد. در صورت عدم وجود لیست مانیفست، آن را ایجاد می‌کند. این گزینه برای ساخت ایمیج‌های چندمعماری مفید است. اگر listName شامل بخش نام رجیستری نباشد، نام رجیستری localhost به ابتدای نام لیست اضافه می‌شود.

--memory, -m=""

محدودیت حافظه (قالب: []، که در آن واحد = b، k، m یا g است)

به شما اجازه می‌دهد حافظه در دسترس کانتینر را محدود کنید. اگر میزبان از حافظه swap پشتیبانی کند، تنظیم حافظه -m می‌تواند بزرگ‌تر از RAM فیزیکی باشد. اگر محدودیت 0 مشخص شود (عدم استفاده از -m)، حافظه کانتینر محدود نخواهد شد. حد واقعی ممکن است به مضربی از اندازه صفحه (page size) سیستم‌عامل به بالا گرد شود (این مقدار بسیار بزرگ خواهد بود، یعنی میلیون‌ها تریلیون).

--memory-swap="LIMIT"

یک مقدار محدودیت برابر با حافظه به علاوه swap. باید همراه با فلگ -m (--memory) استفاده شود. مقدار LIMIT مربوط به swap همیشه باید از مقدار -m (--memory) بزرگ‌تر باشد. به طور پیش‌فرض، LIMIT سواپ دو برابر مقدار --memory تنظیم خواهد شد.

قالب LIMIT به صورت <number>[<unit>] است. واحد می‌تواند b (بایت)، k (کیلوبایت)، m (مگابایت)، یا g (گیگابایت) باشد. اگر واحدی مشخص نکنید، b استفاده می‌شود. برای فعال‌سازی swap نامحدود، مقدار LIMIT را روی -1 تنظیم کنید.

--metadata-file MetadataFile

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

--mount mount-instruction

این مونت را پیش از اجرا به هر دستور RUN در Containerfile اضافه می‌کند. برای مثال:

buildah build --mount type=secret,id=mysecret ...

و یک ورودی Containerfile به صورت:

RUN cat /run/secrets/mysecret

اثری مشابه دستور زیر دارد:

RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret

--network, --net=mode

پیکربندی فضاهای نام شبکه را هنگام پردازش دستورالعمل‌های RUN تنظیم می‌کند.

مقادیر معتبر mode عبارتند از:

--no-cache

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

--no-hostname

فایل /etc/hostname را در کانتینر برای دستورالعمل‌های RUN ایجاد نمی‌کند.

به طور پیش‌فرض، Buildah فایل /etc/hostname را مدیریت کرده و نام میزبان کانتینر را اضافه می‌کند. هنگامی که گزینه --no-hostname تنظیم شود، فایل /etc/hostname ایمیج (در صورت وجود) بدون تغییر حفظ خواهد شد.

--no-hosts

فایل /etc/hosts را در کانتینر برای دستورالعمل‌های RUN ایجاد نمی‌کند.

به طور پیش‌فرض، Buildah فایل /etc/hosts را مدیریت کرده و آدرس IP خود کانتینر را اضافه می‌کند. گزینه --no-hosts این مورد را غیرفعال می‌کند و فایل /etc/hosts ایمیج بدون تغییر حفظ خواهد شد. با گزینه --add-host تداخل دارد.

--omit-history bool-value

حذف اطلاعات تاریخچه ساخت در ایمیج ساخته‌شده (پیش‌فرض false).

این گزینه برای مواردی مفید است که کاربران نهایی صراحتاً می‌خواهند --omit-history را برای حذف بخش اختیاری History از ایمیج‌های ساخته‌شده تنظیم کنند، یا هنگام کار با ایمیج‌هایی که توسط ابزارهای ساختی ساخته شده‌اند که اطلاعات History را در ایمیج‌های خود قرار نمی‌دهند.

--os="OS"

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

--os-feature feature

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

اگر feature دارای یک علامت - در انتها باشد، آن feature از مجموعه ویژگی‌های مورد نیازی که در ایمیج فهرست می‌شوند حذف می‌گردد.

--os-version version

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

--output, -o=""

خروجی اضافی (قالب: type=local,dest=path)

گزینه --output (یا -o) رفتار پیش‌فرض ساخت ایمیج کانتینر را با دادن اجازه به کاربران جهت صادر کردن محتویات ایمیج به صورت فایل‌هایی در سیستم‌فایل محلی تکمیل می‌کند، که می‌تواند برای تولید باینری‌های محلی، تولید کد و غیره مفید باشد.

مقدار --output دنباله‌ای از جفت‌های کلید=مقدار (key=value) جداشده با کاما است که نوع خروجی و گزینه‌ها را تعیین می‌کند.

کلیدهای (keys) پشتیبانی‌شده عبارتند از:
dest: مقصد خروجی صادرشده. می‌تواند برای نشان دادن خروجی استاندارد روی - یا یک مسیر مطلق یا نسبی تنظیم شود.
type: نوع خروجی نوشته‌شده را تعیین می‌کند. باید یکی از مقادیر فهرست‌شده در زیر باشد.

مقادیر معتبر type عبارتند از:
local: نوشتن فایل‌های حاصل از ساخت در یک دایرکتوری در سمت کلاینت.
tar: نوشتن فایل‌های حاصل به عنوان یک فایل تار یکتا (.tar).

همچنین به عنوان جایگزین به جای دنباله‌ای جداشده با کاما، مقدار --output می‌تواند تنها خود مقصد باشد (در قالب **dest**) (مانند --output some-path، --output -)، و در صورتی که مقصد خروجی - باشد نوع (type) برابر با tar در نظر گرفته می‌شود، و در غیر این صورت local خواهد بود.

برچسب‌های زمانی (Timestamps) روی محتویات خروجی دقیقاً منطبق با مقدار مشخص‌شده با استفاده از فلگ --timestamp، یا دقیقاً منطبق با مقدار مشخص‌شده برای فلگ --source-date-epoch (در صورت تعیین هر یک از آن‌ها) تنظیم خواهد شد.

توجه داشته باشید که از گزینه --tag نیز می‌توان برای نوشتن ایمیج در هر مکانی که توسط containers-transports(5) توصیف شده است استفاده کرد.

--pid how

پیکربندی فضاهای نام PID را هنگام پردازش دستورالعمل‌های RUN تعیین می‌کند. مقدار پیکربندی‌شده می‌تواند "" (رشته خالی) یا "private" باشد تا نشان دهد یک فضای نام PID جدید باید ایجاد شود، یا می‌تواند "host" باشد تا نشان دهد فضای نام PID که خود buildah در آن در حال اجراست باید مجدداً استفاده شود، یا می‌تواند مسیر یک فضای نام PID باشد که قبلاً توسط فرآیند دیگری استفاده شده است.

--platform="OS/ARCH[/VARIANT]"

تنظیم OS/ARCH ایمیج ساخته‌شده (و ایمیج پایه آن، در صورتی که ساخت از آن استفاده کند) روی مقدار ارائه‌شده به جای استفاده از سیستم‌عامل و معماری فعلی میزبان (برای مثال linux/arm، linux/arm64، linux/amd64).

فلگ --platform می‌تواند بیش از یک بار مشخص شود، یا فهرستی از مقادیر جداشده با کاما به عنوان شناسه به آن داده شود. هنگامی که بیش از یک پلتفرم مشخص شده باشد، باید از گزینه --manifest به جای گزینه --tag استفاده شود.

جفت‌های OS/ARCH مواردی هستند که توسط زبان برنامه‌نویسی Go استفاده می‌شوند. در چندین مورد، مقدار ARCH برای یک پلتفرم با مقدار تولیدشده توسط ابزارهای دیگر مانند دستور arch تفاوت دارد. ترکیب‌های معتبر نام سیستم‌عامل و معماری به عنوان مقادیر $GOOS و $GOARCH در https://golang.org/doc/install/source#environment فهرست شده‌اند، و همچنین می‌توان آن‌ها را با اجرای go tool dist list پیدا کرد.

دستور buildah build امکان ساخت ایمیج‌ها را برای تمام معماری‌های لینوکس، حتی معماری‌های غیربومی (non-native) فراهم می‌کند. هنگام ساخت ایمیج‌ها برای یک معماری متفاوت، دستورالعمل‌های RUN به نرم‌افزار شبیه‌سازی نصب‌شده روی میزبان نیاز دارند که توسط بسته‌هایی مانند qemu-user-static ارائه می‌شود. نکته: در صورت امکان همیشه ترجیح داده می‌شود که ایمیج‌ها روی معماری بومی ساخته شوند.

نکته: گزینه --platform نباید در ترکیب با گزینه‌های --arch، --os یا --variant استفاده شود.

--pull

سیاست دریافت (pull) ایمیج. در صورت مشخص نشدن، مقدار پیش‌فرض missing است. اگر آرگومان صریح --pull بدون هیچ مقداری ارائه شود، از رفتار always استفاده می‌شود.

--quiet, -q

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

--retry attempts

تعداد دفعات تلاش مجدد در صورت بروز خطا هنگام ارسال یا دریافت (push/pull) ایمیج‌ها به/از رجیستری.

پیش‌فرض 3 است.

--retry-delay duration

مدت زمان تاخیر بین تلاش‌های مجدد در صورت بروز خطا هنگام ارسال یا دریافت (push/pull) ایمیج‌ها به/از رجیستری.

پیش‌فرض 2s است.

--rewrite-timestamp

هنگام تولید لایه‌های جدید برای ایمیج، با جایگزین کردن هرگونه مهرزمانی (timestamp) پس از مقدار استفاده‌شده توسط فلگ --source-date-epoch (در صورت ارائه) با همان مقدار، اطمینان حاصل کن که هیچ محتوای تازه اضافه‌شده‌ای مهرزمانی بعد از آن مقدار را نداشته باشد.

--rm bool-value

حذف کانتینرهای میانی پس از ساخت موفقیت‌آمیز (پیش‌فرض true).

--runtime path

مسیر (path) به یک زمان‌اجرای (runtime) جایگزین سازگار با OCI، که برای اجرای دستورات مشخص‌شده توسط دستورالعمل RUN استفاده خواهد شد. مقدار پیش‌فرض runc است، یا crun هنگامی که سیستم برای استفاده از cgroups V2 پیکربندی شده باشد.

نکته: شما همچنین می‌توانید با تنظیم متغیر محیطی BUILDAH_RUNTIME، زمان‌اجرای پیش‌فرض را بازنویسی کنید. export BUILDAH_RUNTIME=/usr/bin/crun

--runtime-flag flag

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

نکته: -- ابتدایی را به فلگ ارسال نکنید. برای ارسال فلگ runc یعنی --log-format json به buildah build، گزینه ارائه‌شده باید به‌صورت --runtime-flag log-format=json باشد.

--save-stages bool-value

حفظ ایمیج‌های مراحل (stages) میانی به جای حذف آن‌ها پس از اتمام ساخت (پیش‌فرض false است). به‌طور پیش‌فرض، Buildah برای صرفه‌جویی در فضا ایمیج‌های مراحل میانی را حذف می‌کند. این گزینه آن ایمیج‌ها را نگه می‌دارد، که می‌تواند برای اشکال‌زدایی ساخت‌های چندمرحله‌ای یا استفاده مجدد از مراحل میانی در ساخت‌های بعدی مفید باشد.

--save-stages می‌تواند همراه با --layers استفاده شود و ساخت‌های بعدی با --layers می‌توانند از لایه‌های میانی حفظ‌شده به عنوان کش (حافظه موقت) استفاده کنند.

هنگامی که با --stage-labels ترکیب شود، تمامی ایمیج‌های مراحل (از جمله ایمیج نهایی) برچسب‌های متادیتا را برای شناسایی و مدیریت آسان‌تر شامل خواهند شد.

--sbom preset

تولید لیست مواد نرم‌افزاری / SBOM (Software Bills Of Materials) برای ایمیج خروجی با اسکن کانتینر در حال کار و زمینه‌های ساخت (build contexts) با استفاده از ترکیب نام‌گذاری‌شده‌ای از ایمیج اسکنر، دستورات اسکنر، و استراتژی ادغام. باید با یک یا چند مورد از --sbom-image-output، --sbom-image-purl-output، --sbom-output، و --sbom-purl-output مشخص شود. الگوهای از پیش‌تنظیم‌شده (presets) شناخته‌شده و مجموعه‌گزینه‌های معادل آن‌ها:

--sbom-image-output path

هنگام تولید SBOM، لیست مواد نرم‌افزاری (SBOM) تولیدشده را در مسیر مشخص‌شده در ایمیج خروجی ذخیره کن. هیچ مقدار پیش‌فرضی وجود ندارد.

--sbom-image-purl-output path

هنگام تولید SBOM، آن‌ها را برای اطلاعات PURL (نشانی اینترنتی بسته / package URL ⟨https://github.com/package-url/purl-spec/blob/master/PURL-SPECIFICATION.rst⟩) اسکن کن، و فهرستی از PURLهای یافت‌شده را در مسیر مشخص‌شده در ایمیج خروجی ذخیره نما. هیچ مقدار پیش‌فرضی وجود ندارد.

--sbom-merge-strategy method

اگر بیش از یک مقدار --sbom-scanner-command استفاده شده باشد، از روش مشخص‌شده برای ادغام خروجی دستورات بعدی با خروجی دستورات قبلی استفاده کن. مقادیر شناخته‌شده عبارتند از:

--sbom-output file

هنگام تولید SBOM، لیست مواد نرم‌افزاری (SBOM) تولیدشده را در پرونده نام‌برده در سیستم‌فایل محلی ذخیره کن. هیچ مقدار پیش‌فرضی وجود ندارد.

--sbom-purl-output file

هنگام تولید SBOM، آن‌ها را برای اطلاعات PURL (نشانی اینترنتی بسته / package URL ⟨https://github.com/package-url/purl-spec/blob/master/PURL-SPECIFICATION.rst⟩) اسکن کن، و فهرستی از PURLهای یافت‌شده را در پرونده نام‌برده در سیستم‌فایل محلی ذخیره نما. هیچ مقدار پیش‌فرضی وجود ندارد.

--sbom-scanner-command image

تولید SBOM با اجرای دستور مشخص‌شده از ایمیج اسکنر. اگر چندین دستور مشخص شده باشد، آن‌ها به ترتیبی که تعیین شده‌اند اجرا می‌شوند. این جایگزینی‌های متنی انجام می‌شوند:
- {ROOTFS}
ریشه فایل‌سیستم ایمیج ساخته‌شده، متصل‌شده به‌صورت bind mount.
- {CONTEXT}
زمینه ساخت (build context) و زمینه‌های ساخت اضافی، متصل‌شده به‌صورت bind mount.
- {OUTPUT}
نام یک پرونده خروجی موقت، برای خواندن و ادغام با سایرین یا کپی شدن در جای دیگر.

--sbom-scanner-image image

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

--secret=id=id[,src=envOrFile][,env=ENV][,type=file|env]

ارسال اطلاعات محرمانه (سکرت / secret) برای استفاده در Containerfile جهت ساخت ایمیج‌ها به روشی امن که در نهایت در ایمیج نهایی ذخیره نشود یا در مراحل دیگر دیده نشود. مقدار سکرت از یک متغیر محیطی یا پرونده با نام ارائه‌شده توسط گزینه "id"، یا با نام تعیین‌شده توسط گزینه "src" (در صورت مشخص شدن)، یا از یک متغیر محیطی مشخص‌شده با گزینه "env" خوانده می‌شود. اطلاعات محرمانه (سکرت) به‌طور پیش‌فرض در مسیر /run/secrets/<id> در کانتینر متصل (mount) خواهد شد.

برای استفاده از سکرت در ادامه، از فلگ --mount در دستورالعمل RUN در داخل یک Containerfile استفاده کنید:

RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret

محل قرارگیری سکرت در کانتینر را می‌توان با استفاده از گزینه‌های "target"، "dst" یا "destination" از فلگ RUN --mount بازنویسی کرد.

RUN --mount=type=secret,id=mysecret,target=/run/secrets/myothersecret cat /run/secrets/myothersecret

همچنین سکرت را می‌توان به‌صورت متغیر محیطی در اختیار فرایند قرار داد:

RUN --mount=type=secret,id=mysecret,env=FOO sh -c 'echo "Hello $FOO"'

نکته: تغییر محتوای پرونده‌های سکرت، موجب بازسازی مجدد لایه‌هایی که از سکرت‌های مذکور استفاده می‌کنند نخواهد شد.

--security-opt=[]

گزینه‌های امنیتی

"apparmor=unconfined" : غیرفعال کردن محدودسازی apparmor برای کانتینر
"apparmor=your-profile" : تنظیم نمایه (profile) محدودسازی apparmor برای کانتینر

"label=user:USER" : تنظیم کاربر برچسب برای کانتینر
"label=role:ROLE" : تنظیم نقش برچسب برای کانتینر
"label=type:TYPE" : تنظیم نوع برچسب برای کانتینر
"label=level:LEVEL" : تنظیم سطح برچسب برای کانتینر
"label=disable" : غیرفعال کردن محدودسازی برچسب برای کانتینر

"mask=/path/1:/path/2": مسیرهایی که باید ماسک شوند که با دونقطه از هم جدا شده‌اند. مسیر ماسک‌شده در داخل کانتینر قابل دسترسی نیست.

"no-new-privileges" : جلوگیری از کسب امتیازات اضافی توسط فرایندهای کانتینر

"seccomp=unconfined" : غیرفعال کردن محدودسازی seccomp برای کانتینر
"seccomp=profile.json : پیکربندی JSON برای فیلتر seccomp

"unmask=ALL یا /path/1:/path/2، یا مسیرهای گسترش‌یافته توسط پوسته (/proc/*): مسیرهایی که باید آن‌ماسک شوند که با دونقطه از هم جدا شده‌اند. در صورت تنظیم روی ALL، تمام مسیرهایی که به‌طور پیش‌فرض ماسک شده یا فقط‌خواندنی هستند را از حالت ماسک خارج می‌کند.
مسیرهای پیش‌فرض ماسک‌شده عبارتند از /proc/acpi, /proc/interrupts, /proc/kcore, /proc/keys, /proc/latency_stats, /proc/sched_debug, /proc/scsi, /proc/timer_list, /proc/timer_stats, /sys/devices/virtual/powercap, /sys/firmware، و /sys/fs/selinux. مسیرهای پیش‌فرض فقط‌خواندنی عبارتند از /proc/asound، /proc/bus، /proc/fs، /proc/irq، /proc/sys، و /proc/sysrq-trigger.

--shm-size=""

اندازه /dev/shm. قالب آن به‌صورت <number><unit> است. number باید بزرگتر از 0 باشد. واحد اختیاری است و می‌تواند b (بایت)، k (کیلوبایت)، m (مگابایت)، یا g (گیگابایت) باشد. اگر واحد را حذف کنید، سیستم از بایت استفاده می‌کند. اگر اندازه را به‌طور کامل حذف کنید، سیستم از 64m استفاده می‌کند.

--sign-by fingerprint

امضای ایمیج ساخته‌شده با استفاده از کلید GPG مطابق با اثرانگشت (fingerprint) مشخص‌شده.

--skip-unused-stages bool-value

صرف‌نظر کردن از مراحلی در ساخت‌های چندمرحله‌ای که تأثیری روی مرحله هدف ندارند (پیش‌فرض true است).

--source-date-epoch seconds

برچسب زمانی «ایجاد شده» (created) را برای تصویر ساخته‌شده بر اساس این تعداد ثانیه از مبدأ زمان (Unix epoch، یعنی ساعت 00:00:00 به وقت UTC در ۱ ژانویه ۱۹۷۰) تنظیم می‌کند (پیش‌فرض استفاده از مقدار تنظیم‌شده در متغیر محیطی SOURCE_DATE_EPOCH، یا زمان فعلی در صورت عدم تنظیم آن است).

برچسب زمانی «created» هنگام ثبت (commit) تصویر در پیکربندی و مانیفست تصویر نوشته می‌شود؛ بنابراین، اجرای همان فرایند ساخت در دو زمان مختلف معمولاً تصاویری با هش‌های sha256 متفاوت تولید می‌کند، حتی اگر هیچ تغییر دیگری در Containerfile و زمینه ساخت (build context) ایجاد نشده باشد.

هنگامی که این فلگ تنظیم شود، یک آرگومان ساخت (build arg) به نام SOURCE_DATE_EPOCH مقدار خود را برای مرحله‌ای که در آن اعلان شده است فراهم می‌کند.

هنگامی که این فلگ تنظیم شود، برچسب زمانی «created» در پیکربندی تصویر همیشه روی زمان مشخص‌شده تنظیم می‌شود، که امکان ساخت تصاویر کاملاً یکسان را در زمان‌های مختلف با استفاده از مجموعه‌ای یکسان از ورودی‌ها فراهم می‌کند.

هنگامی که این فلگ تنظیم شود، خروجی نوشته‌شده طبق مشخصات فلگ --output دقیقاً حامل برچسب زمانی مشخص‌شده خواهد بود.

با فلگ مشابه --timestamp که زمان مشخص‌شده‌اش را بر روی محتویات لایه‌های جدید نیز اعمال می‌کند، تداخل دارد.

--source-policy-file pathname

مسیر یک فایل JSON سیاست منبع (source policy) سازگار با BuildKit را مشخص می‌کند. هنگام تعیین این گزینه، مراجع منبع (مانند تصاویر پایه در دستورالعمل‌های FROM) پیش از استفاده، بر اساس قوانین این سیاست ارزیابی می‌شوند.

سیاست‌های منبع امکان کنترل تصاویری را که می‌توانند به عنوان تصویر پایه استفاده شوند، و همچنین امکان تبدیل اختیاری مراجع تصویر (به عنوان مثال، پین کردن تگ‌ها به دایجست‌های خاص) را بدون نیاز به تغییر دادن فایل‌های Containerfile فراهم می‌کنند. این قابلیت برای اعمال سیاست‌های سازمانی و تضمین بازتولیدپذیری ساخت (build reproducibility) مفید است.

فایل سیاست یک سند JSON شامل آرایه‌ای از قوانین است. هر قانون شامل موارد زیر است: - action: عملیاتی که هنگام تطابق قانون انجام می‌شود. عملیات معتبر عبارتند از:
- ALLOW: مجاز دانستن صریح منبع (بدون هیچ تبدیلی).
- DENY: مسدود کردن منبع و شکست فرایند ساخت.
- CONVERT: تبدیل منبع به یک مرجع متفاوت مشخص‌شده در updates. - selector: مشخص می‌کند قانون برای کدام منابع اعمال شود.
- identifier: شناسه منبع جهت تطابق (برای مثال، docker-image://docker.io/library/alpine:latest).
- matchType: نحوه تطابق شناسه. انواع معتبر عبارتند از EXACT و WILDCARD (پشتیبانی از الگوهای glob شامل * و ?). در صورت عدم تعیین، پیش‌فرض روی WILDCARD قرار دارد. - updates: برای عملیات CONVERT، شناسه جایگزین را مشخص می‌کند.

قوانین به ترتیب ارزیابی می‌شوند؛ نخستین قانون منطبق اعمال خواهد شد. اگر هیچ قانونی مطابقت نداشته باشد، منبع به‌صورت پیش‌فرض مجاز در نظر گرفته می‌شود.

نکته: قوانین CONVERT در سیاست منبع پس از جایگزینی‌های --build-context اما پیش از هرگونه جایگزینی مشخص‌شده در containers-registries.conf(5) پردازش می‌شوند. این سازوکار روش‌های متعددی را برای بازنویسی تصویر پایه مورد استفاده در یک مرحله خاص به ترتیب اولویت زیر فراهم می‌کند: ابتدا --build-context، سپس سیاست منبع، و در نهایت registries.conf.

نمونه فایل سیاست که alpine:latest را به یک دایجست خاص پین می‌کند:

{
  "rules": [
    {
      "action": "CONVERT",
      "selector": {
        "identifier": "docker-image://docker.io/library/alpine:latest"
      },
      "updates": {
        "identifier": "docker-image://docker.io/library/alpine@sha256:..."
      }
    }
  ]
}

نمونه فایل سیاست که تمامی تصاویر ubuntu را مسدود می‌کند:

{
  "rules": [
    {
      "action": "DENY",
      "selector": {
        "identifier": "docker-image://docker.io/library/ubuntu:*",
        "matchType": "WILDCARD"
      }
    }
  ]
}

--squash

تمامی لایه‌ها، از جمله لایه‌های متعلق به تصویر (تصاویر) پایه را در یک لایه واحد ادغام (squash) می‌کند. (پیش‌فرض false است).

به‌صورت پیش‌فرض، Buildah لایه‌های موجود تصویر پایه را حفظ کرده و در هنگام ساخت تنها یک لایه جدید اضافه می‌کند. گزینه --layers می‌تواند برای حفظ لایه‌های میانی ساخت استفاده شود.

--ssh=default|id[=socket>|[,]

سوکت عامل SSH یا کلیدهایی که قرار است در دسترس فرایند ساخت قرار گیرند. مسیر سوکت می‌تواند خالی رها شود تا از مقدار default=$SSH_AUTH_SOCK استفاده شود.

برای استفاده بعدی از عامل ssh، از فلگ --mount در دستورالعمل RUN درون یک Containerfile استفاده کنید:

RUN --mount=type=secret,id=id mycmd

نکته: هنگام استفاده از کاربری غیر از کاربر پیش‌فرض root، باید یکی از گزینه‌های mode، uid یا gid همراه با گزینه‌های mount مشخص شود. برای مثال، در دسترس قرار دادن سوکت ssh برای کاربر app با uid=50000:

# Switch to application user (Note that uid depends on container image)
USER app
# ...and check whether ssh identities are available
RUN --mount=type=ssh,uid=50000
    ssh-add -L

--stage-labels bool-value

افزودن برچسب‌های متادیتا به تمامی تصاویر مراحل میانی در ساخت چندمرحله‌ای، از جمله تصویر نهایی (پیش‌فرض false است). این گزینه نیازمند فعال بودن --save-stages است.

در صورت فعال بودن، تمام تصاویر مراحل میانی و تصویر نهایی با موارد زیر برچسب‌گذاری می‌شوند:
- io.buildah.stage.name: نام مستعار مرحله (از FROM ... AS alias)، یا موقعیت مرحله در صورت عدم تعیین نام مستعار
- io.buildah.stage.base: تصویر پایه استفاده‌شده توسط این مرحله (pullspec یا شناسه تصویر در صورتی که مرحله از مرحله دیگری به عنوان پایه استفاده کند)

این برچسب‌ها شناسایی، جستجو و مدیریت تصاویر حاصل از ساخت‌های چندمرحله‌ای را آسان‌تر می‌کنند.

--stdin

انتقال ورودی استاندارد (stdin) به کانتینرهای دستور RUN. گاهی دستوراتی که با RUN در داخل یک Containerfile اجرا می‌شوند می‌خواهند از کاربر درخواست اطلاعات کنند؛ به عنوان مثال apt که برای نصب درخواست تأییدیه می‌کند. برای امکان تعامل از طریق ترمینال در طول فرایند ساخت، از --stdin استفاده کنید.

--tag, -t imageName

نامی را مشخص می‌کند که در صورت تکمیل موفقیت‌آمیز فرایند ساخت، به تصویر حاصل اختصاص داده خواهد شد. اگر imageName شامل بخش نام رجیستری نباشد، نام رجیستری localhost به ابتدای نام تصویر افزوده خواهد شد.

گزینه --tag از تمامی پروتکل‌های انتقال موجود در containers-transports(5) پشتیبانی می‌کند. در صورت عدم تعیین پروتکل انتقال، پروتکل containers-storage (یعنی فضای ذخیره‌سازی محلی) استفاده می‌شود.

buildah build --tag=oci-archive:./foo.ociarchive .

buildah build -t quay.io/username/foo .

--target stageName

مرحله ساخت هدف (تارگت) را برای ساخت مشخص می‌کند. هنگام ساخت یک Containerfile با چندین مرحله ساخت، می‌توان از --target برای مشخص کردن یک مرحله ساخت میانی با نام آن به عنوان مرحله نهایی برای تصویر حاصل استفاده کرد. دستورات پس از مرحله هدف نادیده گرفته خواهند شد.

--timestamp seconds

برچسب زمانی «ایجاد شده» (created) را برای تصویر ساخته‌شده بر اساس این تعداد ثانیه از مبدأ زمان (Unix epoch، یعنی ساعت 00:00:00 به وقت UTC در ۱ ژانویه ۱۹۷۰) تنظیم می‌کند (پیش‌فرض زمان فعلی است).

برچسب زمانی «created» هنگام ثبت (commit) تصویر در پیکربندی و مانیفست تصویر نوشته می‌شود؛ بنابراین، اجرای همان فرایند ساخت در دو زمان مختلف معمولاً تصاویری با هش‌های sha256 متفاوت تولید می‌کند، حتی اگر هیچ تغییر دیگری در Containerfile و زمینه ساخت (build context) ایجاد نشده باشد.

هنگامی که --timestamp تنظیم شود، برچسب زمانی «created» همیشه روی زمان مشخص‌شده تنظیم می‌شود، که امکان ساخت تصاویر کاملاً یکسان را در زمان‌های مختلف با استفاده از مجموعه‌ای یکسان از ورودی‌ها فراهم می‌کند.

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

با فلگ مشابه --source-date-epoch که به‌صورت پیش‌فرض بر برچسب‌های زمانی محتویات لایه‌ها تأثیری ندارد، تداخل دارد.

--tls-verify bool-value

الزام استفاده از HTTPS و اعتبارسنجی گواهی‌ها هنگام ارتباط با رجیستری‌های کانتینر (پیش‌فرض true است) و بازیابی محتوا از مکان‌های HTTPS برای دستورالعمل‌های ADD. اعتبارسنجی TLS هنگام ارتباط با یک رجیستری ناامن قابل استفاده نیست.

--ulimit type=soft-limit[:hard-limit]

محدودیت‌های منابع را برای اعمال بر روی فرایندهای راه‌اندازی‌شده هنگام پردازش دستورالعمل‌های RUN مشخص می‌کند. این گزینه می‌تواند چندین بار مشخص شود. انواع منابع شناخته‌شده عبارتند از:
"core": حداکثر اندازه تخلیه حافظه هسته (core dump) (دستور ulimit -c)
"cpu": حداکثر زمان CPU (دستور ulimit -t)
"data": حداکثر اندازه بخش داده‌های یک فرایند (data segment) (دستور ulimit -d)
"fsize": حداکثر اندازه فایل‌های جدید (ulimit -f)
"locks": حداکثر تعداد قفل‌های فایل (ulimit -x)
"memlock": حداکثر مقدار حافظه قفل‌شده (ulimit -l)
"msgqueue": حداکثر مقدار داده در صف‌های پیام (ulimit -q)
"nice": تنظیم اولویت niceness (دستورات nice -n، ulimit -e)
"nofile": حداکثر تعداد فایل‌های باز (ulimit -n)
"nofile": حداکثر تعداد فایل‌های باز (1048576)؛ هنگام اجرا توسط کاربر root
"nproc": حداکثر تعداد فرایندها (ulimit -u)
"nproc": حداکثر تعداد فرایندها (1048576)؛ هنگام اجرا توسط کاربر root
"rss": حداکثر اندازه حافظه مقیم یک فرایند (RSS) (دستور ulimit -m)
"rtprio": حداکثر اولویت زمان‌بندی بی‌درنگ (real-time) (دستور ulimit -r)
"rttime": حداکثر زمان اجرای بی‌درنگ بین فراخوان‌های سیستمی مسدودکننده
"sigpending": حداکثر تعداد سیگنال‌های در انتظار (ulimit -i)
"stack": حداکثر اندازه پشته (stack) (دستور ulimit -s)

--unsetannotation annotation

حذف حاشیه‌نویسی (annotation) تصویر، که مانع از به ارث رسیدن حاشیه‌نویسی از تصویر پایه می‌شود.

--unsetenv env

حذف متغیرهای محیطی از تصویر نهایی.

--unsetlabel label

حذف برچسب (label) تصویر، که مانع از به ارث رسیدن برچسب از تصویر پایه می‌شود.

--userns how

پیکربندی فضاهای نام کاربری (user namespaces) را هنگام پردازش دستورالعمل‌های RUN تنظیم می‌کند. مقدار پیکربندی‌شده می‌تواند "" (رشته خالی)، "private" یا "auto" باشد تا نشان دهد که باید یک فضای نام کاربری جدید ایجاد شود، می‌تواند "host" باشد تا نشان دهد فضای نام کاربری که در آن خود buildah در حال اجراست باید مجدداً استفاده شود، یا می‌تواند مسیر یک فضای نام کاربری باشد که هم‌اکنون توسط فرایند دیگری در حال استفاده است.

auto: ایجاد خودکار یک فضای نام کاربری یکتا.

فلگ --userns=auto مستلزم این است که نام کاربری containers و محدوده‌ای از شناسه‌های کاربری فرعی (subordinate user IDs) که کانتینر ساخت مجاز به استفاده از آن‌ها است در فایل‌های /etc/subuid و /etc/subgid مشخص شده باشند.

مثال: containers:2147483647:2147483648.

برنامه Buildah محدوده‌های یکتایی از UIDها و GIDها را از شناسه‌های کاربری فرعی containers اختصاص می‌دهد. اندازه این محدوده‌ها بر اساس تعداد UIDهای مورد نیاز در تصویر است. تعداد UIDها و GIDها را می‌توان با گزینه size بازنویسی کرد.

گزینه‌های معتبر auto:

--userns-gid-map mapping

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

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

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

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

--userns-gid-map-group group

مشخص می‌کند نگاشت GID که باید برای تعیین مالکیت در سطح سیستم فایل بر روی محتویات کانتینر در حال کار استفاده شود، می‌تواند در مدخل‌های مربوط به گروه مشخص‌شده در فایل /etc/subgid یافت شود. دستوراتی که هنگام پردازش دستورالعمل‌های RUN اجرا می‌شوند، به‌طور پیش‌فرض در فضاهای نام کاربری اختصاصی خود که با استفاده از نگاشت‌های UID و GID پیکربندی شده‌اند اجرا خواهند شد. اگر --userns-uid-map-user مشخص شده باشد، اما --userns-gid-map-group مشخص نشده باشد، buildah فرض خواهد کرد که نام کاربر مشخص‌شده یک نام گروه مناسب برای استفاده به‌عنوان تنظیم پیش‌فرض این گزینه نیز هست.

کاربران می‌توانند نگاشت‌ها را مستقیماً با استفاده از --userns-gid-map که در صفحه راهنمای buildah(1) توضیح داده شده است مشخص کنند.

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

--userns-uid-map mapping

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

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

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

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

--userns-uid-map-user user

مشخص می‌کند نگاشت UID که باید برای تعیین مالکیت در سطح سیستم فایل بر روی محتویات کانتینر در حال کار استفاده شود، می‌تواند در مدخل‌های مربوط به کاربر مشخص‌شده در فایل /etc/subuid یافت شود. دستوراتی که هنگام پردازش دستورالعمل‌های RUN اجرا می‌شوند، به‌طور پیش‌فرض در فضاهای نام کاربری اختصاصی خود که با استفاده از نگاشت‌های UID و GID پیکربندی شده‌اند اجرا خواهند شد. اگر --userns-gid-map-group مشخص شده باشد، اما --userns-uid-map-user مشخص نشده باشد، buildah فرض خواهد کرد که نام گروه مشخص‌شده یک نام کاربری مناسب برای استفاده به‌عنوان تنظیم پیش‌فرض این گزینه نیز هست.

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

--uts how

پیکربندی فضاهای نام UTS را هنگام پردازش دستورالعمل‌های RUN تنظیم می‌کند. مقدار پیکربندی‌شده می‌تواند "" (رشته خالی) یا "container" باشد تا نشان دهد یک فضای نام UTS جدید باید ایجاد شود، یا می‌تواند "host" باشد تا نشان دهد فضای نام UTS که خود buildah در آن در حال اجراست باید بازاستفاده شود، یا می‌تواند مسیری به یک فضای نام UTS باشد که پیش‌تر توسط فرایند دیگری در حال استفاده است.

--variant=""

گونه (variant) معماری ایمیجی که باید دریافت شود را تنظیم می‌کند.

--volume, -v[=[HOST-DIR:CONTAINER-DIR[:OPTIONS]]]

یک دایرکتوری میزبان را هنگام اجرای دستورالعمل‌های RUN در طول فرایند ساخت به درون کانتینرها متصل (mount) می‌کند. گزینه‌های OPTIONS فهرستی جداشده با کاما هستند و می‌توانند شامل موارد زیر باشند:

مسیر CONTAINER-DIR باید یک مسیر مطلق مانند /src/docs باشد. مسیر HOST-DIR نیز باید یک مسیر مطلق باشد. Buildah مسیر HOST-DIR را به مسیری که مشخص می‌کنید bind-mount می‌کند. برای نمونه، اگر /foo را به‌عنوان مسیر میزبان بدهید، Buildah محتویات /foo را در سیستم فایل کانتینر روی میزبان کپی کرده و آن را به درون کانتینر bind-mount می‌کند.

می‌توانید چندین گزینه -v را برای متصل کردن یک یا چند نقطه اتصال به یک کانتینر مشخص کنید.

اتصال‌های حجم محافظت‌شده در برابر نوشتن (Write Protected Volume Mounts)

می‌توانید پسوند :ro یا :rw را به یک حجم اضافه کنید تا به‌ترتیب در حالت فقط‌خواندنی یا خواندنی-نوشتنی متصل شود. به‌طور پیش‌فرض، حجم‌ها به‌صورت خواندنی-نوشتنی متصل می‌شوند. مثال‌ها را ببینید.

تغییر مالکیت اتصال‌های حجم (Chowning Volume Mounts)

به‌طور پیش‌فرض، Buildah مالک و گروه دایرکتوری‌های حجم مبدأ متصل‌شده به کانتینرها را تغییر نمی‌دهد. اگر کانتینری در یک فضای نام کاربری (user namespace) جدید ایجاد شود، UID و GID درون کانتینر ممکن است با UID و GID متفاوتی روی میزبان متناظر باشند.

پسوند :U به Buildah می‌گوید تا بر اساس UID و GID درون کانتینر، از UID و GID درست میزبان برای تغییر دادن مالک و گروه حجم مبدأ استفاده کند.

برچسب‌گذاری اتصال‌های حجم (Labeling Volume Mounts)

سیستم‌های برچسب‌گذاری مانند SELinux نیازمند قرارگیری برچسب‌های مناسب روی محتوای حجم متصل‌شده به کانتینر هستند. بدون برچسب، سیستم امنیتی ممکن است از استفاده فرایندهای در حال اجرا درون کانتینر از محتوا جلوگیری کند. به‌طور پیش‌فرض، Buildah برچسب‌های تنظیم‌شده توسط سیستم‌عامل را تغییر نمی‌دهد.

برای تغییر یک برچسب در بافت کانتینر، می‌توانید یکی از دو پسوند :z یا :Z را به اتصال حجم اضافه کنید. این پسوندها به Buildah می‌گویند که اشیاء فایل روی حجم‌های اشتراکی را دوباره برچسب‌گذاری کند. گزینه z به Buildah می‌گوید که دو کانتینر محتوای حجم را به اشتراک می‌گذارند. در نتیجه، Buildah محتوا را با یک برچسب محتوای مشترک برچسب‌گذاری می‌کند. برچسب‌های حجم مشترک به همه کانتینرها اجازه خواندن/نوشتن محتوا را می‌دهند. گزینه Z به Buildah می‌گوید که محتوا را با یک برچسب اختصاصی غیرمشترک برچسب‌گذاری کند. تنها کانتینر فعلی می‌تواند از یک حجم اختصاصی استفاده کند.

اتصال‌های حجم اورلی (Overlay Volume Mounts)

فلگ :O به Buildah می‌گوید که دایرکتوری را از میزبان با استفاده از سیستم فایل Overlay به‌عنوان یک فضای ذخیره‌سازی موقت متصل کند. کانتینرهای دستور RUN مجاز هستند محتویات درون نقطه اتصال را تغییر دهند و این تغییرات در فضای ذخیره‌سازی کانتینر در یک دایرکتوری جداگانه ذخیره می‌شوند. در اصطلاحات سامانه فایل چندلایه (Overlay FS)، دایرکتوری مبدأ لایه زیرین (lower) و دایرکتوری ذخیره‌سازی کانتینر لایه بالایی (upper) خواهد بود. تغییرات اعمال‌شده بر نقطه اتصال هنگام پایان اجرای دستور RUN از بین می‌روند، شبیه به یک نقطه اتصال tmpfs.

هر اجرای بعدی از دستورهای RUN محتوای دایرکتوری مبدأ اصلی را می‌بیند؛ هرگونه تغییری از دستورات قبلی RUN دیگر وجود نخواهد داشت.

یک کاربرد اتصال overlay، به اشتراک گذاشتن حافظه نهان بسته‌ها (package cache) از میزبان به درون کانتینر برای افزایش سرعت ساخت است.

نکته:

به‌طور پیش‌فرض حجم‌های bind mount شده به‌صورت private هستند. بدین معنا که هرگونه اتصال انجام‌شده درون کانتینر روی میزبان قابل مشاهده نخواهد بود و برعکس. این رفتار را می‌توان با مشخص کردن ویژگی انتشار اتصال حجم (propagation property) تغییر داد.

هنگامی که خط‌مشی انتشار اتصال روی shared تنظیم شود، هرگونه اتصال انجام‌شده درون کانتینر روی آن حجم، هم برای میزبان و هم برای کانتینر قابل مشاهده خواهد بود. هنگامی که خط‌مشی انتشار اتصال روی slave تنظیم شود، انتشار یک‌طرفه اتصال فعال شده و هرگونه اتصال انجام‌شده روی میزبان برای آن حجم تنها درون کانتینر قابل مشاهده خواهد بود. برای کنترل ویژگی انتشار اتصال حجم از فلگ انتشار :[r]shared، :[r]slave یا :[r]private استفاده کنید. ویژگی انتشار را تنها می‌توان برای حجم‌های bind mount شده مشخص کرد، نه حجم‌های داخلی یا حجم‌های نام‌گذاری‌شده. برای اینکه انتشار اتصال روی نقطه اتصال مبدأ (نقطه اتصالی که دایرکتوری مبدأ روی آن متصل شده است) کار کند، باید ویژگی‌های انتشار مناسب را داشته باشد. برای حجم‌های shared، نقطه اتصال مبدأ باید shared باشد. و برای حجم‌های slave، اتصال مبدأ باید shared یا slave باشد. [1] ⟨#Footnote1⟩

از دستور df <source-dir> برای تعیین نقطه اتصال مبدأ و سپس از findmnt -o TARGET,PROPAGATION <source-mount-dir> برای تعیین ویژگی‌های انتشار نقطه اتصال مبدأ استفاده کنید؛ اگر ابزار findmnt در دسترس نیست، نقطه اتصال مبدأ را می‌توان با نگاه کردن به مدخل اتصال در /proc/self/mountinfo مشخص کرد. به optional fields نگاه کنید و ببینید آیا ویژگی انتشاری مشخص شده است یا خیر. shared:X به این معنی است که نقطه اتصال shared است، master:X به این معنی است که نقطه اتصال slave است و اگر چیزی وجود نداشته باشد به این معنی است که نقطه اتصال private است. [1] ⟨#Footnote1⟩

برای تغییر ویژگی‌های انتشار یک نقطه اتصال، از دستور mount استفاده کنید. برای نمونه، جهت bind mount کردن دایرکتوری مبدأ /foo، دستورهای mount --bind /foo /foo و mount --make-private --make-shared /foo را اجرا کنید. این کار /foo را به یک نقطه اتصال shared تبدیل می‌کند. ویژگی‌های انتشار نقطه اتصال مبدأ را می‌توان مستقیماً تغییر داد. برای نمونه اگر / نقطه اتصال مبدأ برای /foo باشد، از دستور mount --make-shared / استفاده کنید تا / را به یک نقطه اتصال shared تبدیل نماید.

متغیرهای زمان ساخت (BUILD TIME VARIABLES)

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

متغیرهای زیر می‌توانند همراه با گزینه --build-arg استفاده شوند تا مقادیر متناظر تنظیم‌شده در Containerfile با استفاده از دستورالعمل ENV را بازنویسی (override) کنند.

لطفاً به بخش استفاده از متغیرهای زمان ساخت ⟨#using-build-time-variables⟩ از مثال‌ها مراجعه کنید.

مثال‌ها (EXAMPLES)

FROM quay.io/skopeo/stable AS builder
RUN --mount=type=bind,target=/src,rw skopeo copy docker://quay.io/fedora/fedora-minimal oci-archive:/src/fedora.ociarchive
FROM --after=builder oci-archive:fedora.ociarchive
# این مرحله پیش از ارزیابی FROM منتظر تکمیل builder می‌ماند

محیط (ENVIRONMENT)

BUILD_REGISTRY_SOURCES

متغیر BUILD_REGISTRY_SOURCES در صورت تنظیم، به عنوان یک شیء JSON در نظر گرفته می‌شود که شامل فهرست‌هایی از نام‌های رجیستری تحت کلیدهای insecureRegistries، blockedRegistries و allowedRegistries است.

هنگام دریافت (pull) یک تصویر از یک رجیستری، اگر نام رجیستری با هر یک از موارد موجود در فهرست blockedRegistries مطابقت داشته باشد، تلاش برای دریافت تصویر رد می‌شود. اگر رجیستری‌هایی در فهرست allowedRegistries وجود داشته باشند و نام رجیستری در آن فهرست نباشد، تلاش برای دریافت تصویر رد خواهد شد.

TMPDIR متغیر محیطی TMPDIR به کاربر اجازه می‌دهد تا مشخص کند فایل‌های موقت در هنگام دریافت (pull) و ارسال (push) تصاویر در کجا ذخیره شوند. پیش‌فرض '/var/tmp' است.

فایل‌ها (FILES)

# مستثنی کردن این محتوا برای تصویر
*/*.c
**/output*
src

*.doc
!Help.doc

همچنین ببینید (SEE ALSO)

buildah(1), cpp(1), buildah-login(1), docker-login(1), namespaces(7), pid_namespaces(7), containers-policy.json(5), containers-registries.conf(5), user_namespaces(7), crun(1), runc(8), containers.conf(5), oci-hooks(5), containers-transports(5), containers-auth.json(5)

پاورقی‌ها (FOOTNOTES)

1: پروژه Buildah به فراگیر بودن (شمولیت)، که ارزش اصلی نرم‌افزارهای متن‌باز است، متعهد است. اصطلاحات انتشار سوارکردن (mount propagation) master و slave استفاده شده در اینجا مشکل‌ساز و تفرقه‌انگیز هستند و باید تغییر کنند. با این حال، این اصطلاحات در حال حاضر در هسته لینوکس استفاده می‌شوند و در حال حاضر باید به همان شکل استفاده شوند. هنگامی که نگه‌دارندگان هسته این کاربرد را اصلاح کنند، Buildah فوراً از آن پیروی خواهد کرد.