podman-pull(1) General Commands Manual podman-pull(1)

podman-pull - دریافت یک ایمیج از یک رجیستری

podman pull [گزینه‌ها] منبع [منبع...]

podman image pull [گزینه‌ها] منبع [منبع...]

podman pull [گزینه‌ها] [شیوه-انتقال]نام[:تگ|@دایجست]

podman image pull [گزینه‌ها] [شیوه-انتقال]نام[:تگ|@دایجست]

دستور podman pull یک ایمیج را از یک رجیستری بر روی رایانه محلی کپی می‌کند. این دستور می‌تواند یک یا چند ایمیج را دریافت کند. اگر ارجاع به ایمیج در آرگومان خط فرمان شامل نام رجیستری نباشد، به آن یک ارجاع «نام کوتاه» (short-name) گفته می‌شود. اگر ایمیج یک ارجاع نام کوتاه باشد، در صورتی که نام مستعاری برای آن در فایل short-name-aliases.conf مشخص نشده باشد، پادمن از کاربر می‌خواهد رجیستری کانتینر مشخصی را برای دریافت ایمیج انتخاب کند. اگر تگ ایمیج مشخص نشود، podman pull به طور پیش‌فرض به سراغ ایمیج با تگ latest (در صورت وجود) رفته و آن را دریافت می‌کند. پس از دریافت ایمیج، پادمن شناسه کامل ایمیج را چاپ می‌کند. همچنین podman pull می‌تواند ایمیج‌ها را با استفاده از دایجست (podman pull image@digest) دریافت کند و برای دریافت ایمیج‌ها از آرشیوها و حافظه ذخیره‌سازی محلی با استفاده از شیوه‌های انتقال گوناگون به کار رود. مهم: ایمیج‌ها در حافظه ذخیره‌سازی محلی ایمیج ذخیره می‌شوند.

منبع (SOURCE) مکانی است که ایمیج کانتینر از آن دریافت می‌شود. این گزینه از تمامی شیوه‌های انتقال موجود در containers-transports(5) پشتیبانی می‌کند. اگر شیوه‌ای برای انتقال مشخص نشود، ورودی مشمول وضوح نام کوتاه (short-name resolution) شده و از شیوه انتقال docker (یعنی رجیستری کانتینر) استفاده می‌شود. برای کلاینت‌های راه دور، از جمله ماشین‌های مک و ویندوز (به استثنای WSL2)، انتقال docker تنها شیوه پشتیبانی‌شده است.

# دریافت از یک رجیستری کانتینر
$ podman pull quay.io/username/myimage
# دریافت از یک رجیستری کانتینر با حل نام کوتاه
$ podman pull fedora
# دریافت از یک رجیستری کانتینر از طریق شیوه انتقال docker
$ podman pull docker://quay.io/username/myimage
# دریافت از یک پوشه محلی
$ podman pull dir:/tmp/myimage
# دریافت از یک فایل تاربال در قالب docker-archive
$ podman pull docker-archive:/tmp/myimage
# دریافت از دیمن محلی داکر
$ sudo podman pull docker-daemon:docker.io/library/myimage:33
# دریافت از یک فایل تاربال در قالب OCI-archive
$ podman pull oci-archive:/tmp/myimage

تمامی ایمیج‌های دارای تگ در مخزن دریافت می‌شوند.

*مهم: هنگام استفاده از گزینه --all-tags، پادمن روی رجیستری‌های جستجو در containers-registries.conf(5) پیمایش نمی‌کند، بلکه همیشه از docker.io برای نام‌های ایمیج بدون صلاحیت کامل استفاده می‌کند.*

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

مسیر فایل احراز هویت. پیش‌فرض در لینوکس ${XDG_RUNTIME_DIR}/containers/auth.json و در ویندوز/macOS برابر با $HOME/.config/containers/auth.json است. این فایل توسط podman login ایجاد می‌شود. اگر وضعیت احراز هویت در آنجا یافت نشود، فایل $HOME/.docker/config.json بررسی می‌شود که با docker login تنظیم می‌شود.

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

استفاده از گواهی‌های موجود در مسیر (*.crt، *.cert، *.key) برای اتصال به رجیستری (پیش‌فرض: /etc/containers/certs.d). برای جزئیات بیشتر به containers-certs.d(5) مراجعه کنید. (این گزینه در کلاینت راه دور پادمن، از جمله ماشین‌های مک و ویندوز (به استثنای WSL2) در دسترس نیست).

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

توجه داشته باشید که اعتبارنامه‌های مشخص‌شده فقط برای احراز هویت در رجیستری‌های هدف استفاده می‌شوند. آن‌ها برای آینه‌ها یا زمانی که رجیستری بازنویسی می‌شود استفاده نخواهند شد (به containers-registries.conf(5) مراجعه کنید)؛ برای احراز هویت در این موارد استفاده از فایل containers-auth.json(5) را مد نظر قرار دهید.

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

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

چاپ پیام راهنما.

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

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

سیاست دریافت ایمیج. مقدار پیش‌فرض always است.

  • always: همیشه ایمیج را دریافت کن و در صورت شکست دریافت خطا اعلام کن.
  • missing: تنها در صورتی ایمیج را دریافت کن که در حافظه محلی کانتینرها یافت نشود. در صورتی که ایمیجی یافت نشود و دریافت ناموفق باشد، خطا اعلام کن.
  • never: هرگز ایمیج را دریافت نکن؛ تنها از نسخه محلی استفاده کن. اگر ایمیج در سطح محلی موجود نباشد، خطا اعلام کن.
  • newer: اگر ایمیج موجود در رجیستری جدیدتر از ایمیج موجود در حافظه محلی کانتینرها باشد، آن را دریافت کن. هنگامی که دایجست‌ها متفاوت باشند ایمیج جدیدتر در نظر گرفته می‌شود؛ زیرا مقایسه برچسب‌های زمانی مستعد خطا است. در صورتی که ایمیج محلی یافت شود، خطاهای دریافت نادیده گرفته می‌شوند.

نادیده گرفتن پیام‌های خروجی اطلاعاتی (که نشان می‌دهند چه دستوری در حال پردازش است و پیشرفت آن چقدر است). فقط پیام خطای نهایی یا اطلاعات تکمیل موفقیت‌آمیز مانند شناسه ایمیج یا کانتینر چاپ می‌شود.

تعداد دفعات تلاش مجدد برای دریافت یا ارسال ایمیج‌ها بین رجیستری و حافظه محلی در صورت بروز شکست. پیش‌فرض 3 است.

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

الزام به استفاده از HTTPS و اعتبارسنجی گواهی‌ها هنگام ارتباط با رجیستری‌ها (پیش‌فرض: true). اگر صریحاً روی true تنظیم شود، اعتبارسنجی TLS انجام می‌شود. اگر روی false تنظیم شود، اعتبارسنجی TLS انجام نمی‌شود. اگر مشخص نشود، اعتبارسنجی TLS انجام می‌شود مگر اینکه رجیستری هدف در containers-registries.conf(5) به عنوان یک رجیستری ناامن ذکر شده باشد.

استفاده از گونه (variant) به جای گونه معماری پیش‌فرض ایمیج کانتینر. برخی ایمیج‌ها می‌توانند از چندین گونه معماری arm مانند arm/v5 و arm/v7 استفاده کنند.

short-name-aliases.conf (/var/cache/containers/short-name-aliases.conf, $HOME/.cache/containers/short-name-aliases.conf)

زمانی که کاربران ایمیج‌هایی را بدون مشخص کردن رجیستری کانتینر محل ذخیره آن‌ها تعیین می‌کنند، به آن «نام کوتاه» (short name) می‌گویند. استفاده از رجیستری‌های جستجوی بدون صلاحیت (unqualified-search) متضمن ابهام است، زیرا مشخص نیست ایمیج ارجاع داده‌شده با نام کوتاه باید از کدام رجیستری دریافت شود.

استفاده از نام‌های کوتاه در معرض خطر برخورد با فضاهای نام تصاحب‌شده (squatted registry namespaces) است. اگر رجیستری‌های جستجوی بدون صلاحیت روی ["public-registry.com", "my-private-registry.com"] تنظیم شده باشند، یک مهاجم ممکن است یک فضای نام از public-registry.com را تصاحب کند به طوری که ایمیج به جای منبع مورد نظر (my-private-registry.com)، از public-registry.com دریافت شود.

اگرچه اکیداً توصیه می‌شود همیشه از ارجاعات ایمیج با صلاحیت کامل (fully-qualified) استفاده شود، اما تغییر استقرارهای موجود که از نام‌های کوتاه استفاده می‌کنند ممکن است ساده نباشد. برای دور زدن ابهام یادشده، می‌توان به اصطلاح نام‌های مستعار نام کوتاه (short-name aliases) را پیکربندی کرد که به یک ارجاع ایمیج کاملاً مشخص اشاره دارند. توزیع‌ها اغلب یک فایل گسترش shortnames.conf پیش‌فرض را در پوشه /etc/containers/registries.conf.d/ ارائه می‌دهند. مدیران سیستم می‌توانند از این مسیر برای افزودن فایل‌های گسترش نام کوتاه محلی خود استفاده کنند.

هنگام دریافت یک ایمیج، اگر کاربر رجیستری کامل را مشخص نکرده باشد، موتورهای کانتینر تلاش می‌کنند نام کوتاه را به یک نام کامل بسط دهند. اگر دستور با یک tty اجرا شود، از کاربر خواسته می‌شود رجیستری را از فهرست پیش‌فرض رجیستری‌های بدون صلاحیت تعریف‌شده در registries.conf انتخاب کند. سپس انتخاب کاربر در یک فایل کش ذخیره می‌شود تا در تمامی بسط‌های نام کوتاه در آینده استفاده شود. نام‌های کوتاه سطح ریشه (Rootful) در /var/cache/containers/short-name-aliases.conf ذخیره می‌شوند. نام‌های کوتاه بدون ریشه (Rootless) در فایل $HOME/.cache/containers/short-name-aliases.conf نگهداری می‌شوند.

برای اطلاعات بیشتر در مورد نام‌های کوتاه به containers-registries.conf(5) مراجعه کنید.

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

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

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

دریافت یک تک‌ایمیج با حل نام کوتاه:

$ podman pull alpine:latest
Resolved "alpine" as an alias (/etc/containers/registries.conf.d/000-shortnames.conf)
Trying to pull docker.io/library/alpine:latest...
Getting image source signatures
Copying blob 5843afab3874 done
Copying config d4ff818577 done
Writing manifest to image destination
Storing signatures
d4ff818577bc193b309b355b02ebc9220427090057b54a59e73b79bdfe139b83

دریافت چندین ایمیج با یا بدون حل نام کوتاه:

podman pull busybox:musl alpine quay.io/libpod/cirros
Trying to pull docker.io/library/busybox:musl...
Getting image source signatures
Copying blob 0c52b060233b [--------------------------------------] 0.0b / 0.0b
Copying config 9ad2c435a8 done
Writing manifest to image destination
Storing signatures
9ad2c435a887e3f723654e09b48563de44aa3c7950246b2e9305ec85dd3422db
Trying to pull docker.io/library/alpine:latest...
Getting image source signatures
Copying blob 5843afab3874 [--------------------------------------] 0.0b / 0.0b
Copying config d4ff818577 done
Writing manifest to image destination
Storing signatures
d4ff818577bc193b309b355b02ebc9220427090057b54a59e73b79bdfe139b83
Trying to pull quay.io/libpod/cirros:latest...
Getting image source signatures
Copying blob 8da581cc9286 done
Copying blob 856628d95d17 done
Copying blob f513001ba4ab done
Copying config 3c82e4d066 done
Writing manifest to image destination
Storing signatures
3c82e4d066cf6f9e50efaead6e3ff7fddddf5527826afd68e5a969579fc4db4a

دریافت یک ایمیج با استفاده از دایجست آن:

$ podman pull alpine@sha256:d7342993700f8cd7aba8496c2d0e57be0666e80b4c441925fc6f9361fa81d10e
Trying to pull docker.io/library/alpine@sha256:d7342993700f8cd7aba8496c2d0e57be0666e80b4c441925fc6f9361fa81d10e...
Getting image source signatures
Copying blob 188c0c94c7c5 done
Copying config d6e46aa247 done
Writing manifest to image destination
Storing signatures
d6e46aa2470df1d32034c6707c8041158b652f38d2a9ae3d7ad7e7532d22ebe0

دریافت یک ایمیج با تعیین یک فایل احراز هویت:

$ podman pull --authfile temp-auths/myauths.json docker://docker.io/umohnani/finaltest
Trying to pull docker.io/umohnani/finaltest:latest...Getting image source signatures
Copying blob sha256:6d987f6f42797d81a318c40d442369ba3dc124883a0964d40b0c8f4f7561d913
 1.90 MB / 1.90 MB [========================================================] 0s
Copying config sha256:ad4686094d8f0186ec8249fc4917b71faa2c1030d7b5a025c29f26e19d95c156
 1.41 KB / 1.41 KB [========================================================] 0s
Writing manifest to image destination
Storing signatures
03290064078cb797f3e0a530e78c20c13dd22a3dd3adf84a5da2127b48df0438

دریافت یک ایمیج از طریق احراز هویت در یک رجیستری:

$ podman pull --creds testuser:testpassword docker.io/umohnani/finaltest
Trying to pull docker.io/umohnani/finaltest:latest...Getting image source signatures
Copying blob sha256:6d987f6f42797d81a318c40d442369ba3dc124883a0964d40b0c8f4f7561d913
 1.90 MB / 1.90 MB [========================================================] 0s
Copying config sha256:ad4686094d8f0186ec8249fc4917b71faa2c1030d7b5a025c29f26e19d95c156
 1.41 KB / 1.41 KB [========================================================] 0s
Writing manifest to image destination
Storing signatures
03290064078cb797f3e0a530e78c20c13dd22a3dd3adf84a5da2127b48df0438

دریافت یک ایمیج با استفاده از اعتبارسنجی TLS:

$ podman pull --tls-verify=false --cert-dir image/certs docker.io/umohnani/finaltest
Trying to pull docker.io/umohnani/finaltest:latest...Getting image source signatures
Copying blob sha256:6d987f6f42797d81a318c40d442369ba3dc124883a0964d40b0c8f4f7561d913
 1.90 MB / 1.90 MB [========================================================] 0s
Copying config sha256:ad4686094d8f0186ec8249fc4917b71faa2c1030d7b5a025c29f26e19d95c156
 1.41 KB / 1.41 KB [========================================================] 0s
Writing manifest to image destination
Storing signatures
03290064078cb797f3e0a530e78c20c13dd22a3dd3adf84a5da2127b48df0438

دریافت یک ایمیج با بازنویسی معماری میزبان:

$ podman pull --arch=arm arm32v7/debian:stretch
Trying to pull docker.io/arm32v7/debian:stretch...
Getting image source signatures
Copying blob b531ae4a3925 done
Copying config 3cba58dad5 done
Writing manifest to image destination
Storing signatures
3cba58dad5d9b35e755b48b634acb3fdd185ab1c996ac11510cc72c17780e13c

دریافت یک ایمیج با حداکثر ۶ بار تلاش مجدد، ۱۰ ثانیه تاخیر بین تلاش‌ها در حالت بی‌صدا:

$ podman --remote pull -q --retry 6 --retry-delay 10s ubi9
4d6addf62a90e392ff6d3f470259eb5667eab5b9a8e03d20b41d0ab910f92170

دریافت یک ایمیج تنها در صورتی که در سطح محلی موجود نباشد:

$ podman pull --policy missing alpine:latest

هرگز ایمیج را دریافت نکن، فقط از نسخه محلی استفاده کن:

$ podman pull --policy never alpine:latest

همیشه ایمیج را دریافت کن حتی اگر در سطح محلی موجود باشد:

$ podman pull --policy always alpine:latest
Trying to pull docker.io/library/alpine:latest...
Getting image source signatures
Copying blob 5843afab3874 done
Copying config d4ff818577 done
Writing manifest to image destination
Storing signatures
d4ff818577bc193b309b355b02ebc9220427090057b54a59e73b79bdfe139b83

podman(1), podman-push(1), podman-login(1), containers-certs.d(5), containers-registries.conf(5), containers-transports(5)

برای راه‌حل‌های مربوط به مشکلات رایج، podman-troubleshooting(7) را ببینید.

جولای ۲۰۱۷، در ابتدا توسط اورواشی موهنانی (Urvashi Mohnani) umohnani@redhat.com گردآوری شد ⟨mailto:umohnani@redhat.com⟩