podman-system-service(1) General Commands Manual podman-system-service(1)

podman-system-service - اجرای یک سرویس رابط برنامه‌نویسی کاربردی (API)

podman system service [options]

دستور podman system service یک سرویس شنونده (listening service) ایجاد می‌کند که به فراخوانی‌های API برای Podman پاسخ می‌دهد. این دستور روی سیستم‌های لینوکس در دسترس است و معمولاً در قالب سرویس‌های systemd اجرا می‌شود. این دستور هنگامی که Podman به‌طور مستقیم روی میزبان ویندوز یا macOS اجرا شود، یا در شرایط دیگری که دستور Podman به یک سرویس راه دور API دسترسی پیدا می‌کند، در دسترس نیست.

رابط برنامه‌نویسی REST ارائه‌شده توسط podman system service به دو بخش تقسیم می‌شود: یک لایهٔ سازگاری که پشتیبانی از API نسخهٔ v1.40 داکر را ارائه می‌دهد، و یک لایهٔ بومی Libpod برای Podman. مستندات لایهٔ دوم در نشانی https://docs.podman.io/en/latest/_static/api.html در دسترس است. هر دو API دارای شماره نسخه هستند، اما سرور درخواست‌هایی را که دارای نسخهٔ پشتیبانی‌نشده باشند رد نمی‌کند.

دستور podman system service از فعال‌سازی سوکت توسط systemd (Socket Activation) پشتیبانی می‌کند. بنابراین هنگامی که دستور در یک سرویس systemd اجرا می‌شود، سرویس API می‌تواند بنا بر تقاضا (on-demand) ارائه گردد. اگر سرویس systemd از قبل در حال اجرا نباشد، به محض اتصال یک کلاینت به سوکت شنونده فعال خواهد شد. سپس systemd دستور podman system service را اجرا می‌کند. پس از مدتی عدم فعالیت (که توسط گزینهٔ --time تعریف می‌شود)، دستور خاتمه می‌یابد. سپس systemd وضعیت سرویس podman.service را به غیرفعال (inactive) تغییر می‌دهد. در این مرحله هیچ فرآیند فعالی از podman system service در حال اجرا نیست و منابع پردازشی غیرضروری هدر نمی‌رود. به محض اینکه کلاینت دیگری متصل شود، systemd مجدداً سرویس را فعال می‌سازد.

فایل‌های واحد systemd که سرویس API پادمن را برای کاربران تعریف می‌کنند عبارتند از:

  • /usr/lib/systemd/user/podman.service
  • /usr/lib/systemd/user/podman.socket

در فایل podman.socket مسیر سوکت یونیکس شنونده به صورت زیر تعریف شده است:

ListenStream=%t/podman/podman.sock

این مسیر شامل مشخص‌کنندهٔ (specifier) ویژهٔ systemd یعنی %t است که systemd آن را به مقدار متغیر محیطی XDG_RUNTIME_DIR بسط می‌دهد (به بخش مشخص‌کننده‌های systemd در صفحه راهنمای systemd.unit(5) مراجعه کنید).

علاوه بر سرویس‌های کاربری systemd، یک سرویس سیستمی systemd به نام podman.service نیز وجود دارد. این سرویس، Podman را در حالت ریشه‌ای (rootful) اجرا می‌کند و از طریق سوکت یونیکس /run/podman/podman.sock در دسترس است. فایل‌های واحد systemd آن عبارتند از:

  • /usr/lib/systemd/system/podman.service
  • /usr/lib/systemd/system/podman.socket

دستور podman system service برای سرویس API از بیش از یک سوکت شنونده پشتیبانی نمی‌کند.

نکته: فایل‌های واحد پیش‌فرض systemd (سیستمی و کاربری) گزینهٔ سطح لاگ را از error به info تغییر می‌دهند. این تغییر اطلاعات بیشتری در مورد هر فراخوانی API ارائه می‌دهد.

برای پشتیبانی از اجرای سرویس API بدون استفاده از سرویس systemd، این دستور یک آرگومان نقطه پایانی (endpoint) اختیاری را در قالب URI می‌پذیرد؛ به عنوان مثال unix:///tmp/foobar.sock یا tcp://localhost:8080. اگر هیچ نقطه‌پایانی مشخص نشود، مقادیر پیش‌فرض استفاده می‌شوند. نقطه پایانی پیش‌فرض برای یک سرویس با دسترسی ریشه (rootful) برابر unix:///run/podman/podman.sock و برای حالت بدون ریشه (rootless) برابر unix://$XDG_RUNTIME_DIR/podman/podman.sock (برای مثال unix:///run/user/1000/podman/podman.sock) است.

برای دسترسی به سرویس API در داخل یک کانتینر: - سوکت را به عنوان یک حجم (volume) مانت کنید - کانتینر را با گزینهٔ --security-opt label=disable اجرا نمایید

لطفاً توجه داشته باشید که API دسترسی کامل به تمامی عملکردهای Podman را فراهم می‌کند و بنابراین امکان اجرای کدهای دلخواه را با اختیارات کاربری که API را اجرا کرده، بدون هیچ‌گونه امکان محدودسازی یا حسابرسی این دسترسی فراهم می‌سازد. مدل امنیتی API بر پایهٔ دسترسی از طریق سوکت یونیکس با مجوزهای استاندارد فایل ساخته شده است که تضمین می‌کند تنها کاربری که سرویس را اجرا کرده قادر به دسترسی به آن خواهد بود. از TLS می‌توان برای ایمن‌سازی این سوکت با ملزم کردن کلاینت‌ها به ارائهٔ گواهی امضاشده توسط یک مرجع صدور گواهی معتبر ("CA") و همچنین احراز هویت سرویس API توسط کلاینت استفاده کرد. ما اکیداً توصیه می‌کنیم که سوکت API را از طریق شبکه (یعنی متصل کردن سرویس به یک نشانی tcp) بدون فعال‌سازی TLS دوطرفه (mutual TLS) جهت احراز هویت کلاینت به اشتراک نگذارید. حتی دسترسی از طریق Localhost نیز خطراتی به همراه دارد؛ چرا که هر کسی در سیستم دسترسی داشته باشد می‌تواند به API دسترسی پیدا کند. اگر دسترسی از راه دور مورد نیاز است، در عوض توصیه می‌کنیم سوکت API را از طریق SSH هدایت (forward) کنید و دسترسی در ماشین مقصد را تا حد امکان محدود سازید. اگر نشانی tcp باید بدون TLS استفاده شود، استفاده از گزینهٔ --cors برای بهبود امنیت توصیه می‌شود.

هدرهای CORS جهت تزریق به پاسخ HTTP. مقدار پیش‌فرض یک رشتهٔ خالی است که هدرهای CORS را غیرفعال می‌کند.

چاپ راهنمای نحوه استفاده از دستور.

مدت زمان تا پایان انقضای نشست بر حسب ثانیه. مقدار پیش‌فرض ۵ ثانیه است. مقدار 0 به معنای عدم وجود محدودیت زمانی است، بنابراین نشست هرگز منقضی نمی‌شود.

مسیر فایل PEM شامل گواهی TLS برای ارائه به کلاینت‌ها. گزینهٔ --tls-key نیز باید ارائه شود.

مسیر فایل PEM شامل مجموعه گواهی‌های TLS جهت اعتبارسنجی اتصالات کلاینت در برابر آن‌ها. اتصالاتی که گواهی ارائه نکنند یا گواهی آن‌ها توسط یکی از این گواهی‌ها امضا نشده باشد، رد خواهند شد.

مسیر فایل PEM شامل کلید خصوصی منطبق با --tls-cert. گزینهٔ --tls-cert نیز باید مشخص شود.

زمان انتظار پیش‌فرض را می‌توان از طریق فیلد service_timeout=VALUE در containers.conf تغییر داد. برای اطلاعات بیشتر به containers.conf(5) مراجعه کنید.

راه‌اندازی سوکت کاربری systemd برای یک سرویس بدون ریشه (rootless):

systemctl --user start podman.socket

پیکربندی متغیر محیطی DOCKER_HOST برای اشاره به سوکت Podman جهت استفاده از طریق ابزارهای Docker API مانند docker-compose:

$ export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock
$ docker-compose up

پیکربندی سوکت systemd برای راه‌اندازی خودکار پس از راه‌اندازی مجدد سیستم و اجرا با کاربر مشخص‌شده:

systemctl --user enable podman.socket
loginctl enable-linger <USER>

راه‌اندازی سوکت systemd برای سرویس با دسترسی ریشه (rootful):

sudo systemctl start podman.socket

پیکربندی سوکت جهت راه‌اندازی خودکار پس از بازراه‌اندازی سیستم:

sudo systemctl enable podman.socket

امکان اجرای API بدون استفاده از فعال‌سازی سوکت systemd نیز وجود دارد. در این حالت API بر حسب تقاضا در دسترس نخواهد بود؛ زیرا دستور پس از سپری شدن زمان عدم فعالیت، خاتمه می‌یابد. اجرای API با زمان انتظار عدم فعالیت ۵ ثانیه بدون استفاده از فعال‌سازی سوکت:

podman system service --time 5

از آنجا که آرگومان URI ارائه نشد، از سوکت پیش‌فرض استفاده شد.

اجرای سرویس API با مسیر سوکت سفارشی و بدون محدودیت زمانی:

podman system service --time 0 unix:///var/run/mypodman.sock

این دستور سرویس API را به صورتی اجرا می‌کند که روی سوکت سفارشی /var/run/mypodman.sock بدون محدودیت زمانی عدم فعالیت (به‌طور نامحدود) گوش می‌دهد.

podman(1), podman-system-connection(1), containers.conf(5)

ژانویه ۲۰۲۰، در ابتدا توسط Brent Baude <bbaude@redhat.com> گردآوری شد. نوامبر ۲۰۲۰، توسط Jhon Honce (jhonce at redhat dot com) به‌روزرسانی شد.