.nh
.TH podman-system-service 1
.SH "نام (NAME)"
podman-system-service \- اجرای یک سرویس رابط برنامه‌نویسی کاربردی (API)

.SH "خلاصه دستور (SYNOPSIS)"
\fBpodman system service\fP [\fIoptions\fP]

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

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

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

.PP
فایل‌های واحد systemd که سرویس API پادمن را برای کاربران تعریف می‌کنند عبارتند از:
.IP \(bu 2
\fI/usr/lib/systemd/user/podman.service\fP
.IP \(bu 2
\fI/usr/lib/systemd/user/podman.socket\fP

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

.EX
ListenStream=%t/podman/podman.sock
.EE

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

.PP
علاوه بر سرویس‌های کاربری systemd، یک سرویس سیستمی systemd به نام \fIpodman.service\fP نیز وجود دارد.
این سرویس، Podman را در حالت ریشه‌ای (rootful) اجرا می‌کند و از طریق سوکت یونیکس \fI/run/podman/podman.sock\fP در دسترس است. فایل‌های واحد systemd آن عبارتند از:
.IP \(bu 2
\fI/usr/lib/systemd/system/podman.service\fP
.IP \(bu 2
\fI/usr/lib/systemd/system/podman.socket\fP

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

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

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

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

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

.SH "گزینه‌ها (OPTIONS)"
.SS \fB--cors\fP
هدرهای CORS جهت تزریق به پاسخ HTTP. مقدار پیش‌فرض یک رشتهٔ خالی است که هدرهای CORS را غیرفعال می‌کند.

.SS \fB--help\fP, \fB-h\fP
چاپ راهنمای نحوه استفاده از دستور.

.SS \fB--time\fP, \fB-t\fP
مدت زمان تا پایان انقضای نشست بر حسب \fIثانیه\fP\&. مقدار پیش‌فرض ۵ ثانیه است. مقدار \fB0\fR به معنای عدم وجود محدودیت زمانی است، بنابراین نشست هرگز منقضی نمی‌شود.

.SS \fB--tls-cert\fP=\fIpath\fP
مسیر فایل PEM شامل گواهی TLS برای ارائه به کلاینت‌ها. گزینهٔ \fB--tls-key\fR نیز باید ارائه شود.

.SS \fB--tls-client-ca\fP=\fIpath\fP
مسیر فایل PEM شامل مجموعه گواهی‌های TLS جهت اعتبارسنجی اتصالات کلاینت در برابر آن‌ها.
اتصالاتی که گواهی ارائه نکنند یا گواهی آن‌ها توسط یکی از این گواهی‌ها امضا نشده باشد، رد خواهند شد.

.SS \fB--tls-key\fP=\fIpath\fP
مسیر فایل PEM شامل کلید خصوصی منطبق با \fB--tls-cert\fR\&. گزینهٔ \fB--tls-cert\fR نیز باید مشخص شود.

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

.SH "مثال‌ها (EXAMPLES)"
راه‌اندازی سوکت کاربری systemd برای یک سرویس بدون ریشه (rootless):

.EX
systemctl --user start podman.socket
.EE

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

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

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

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

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

.EX
sudo systemctl start podman.socket
.EE

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

.EX
sudo systemctl enable podman.socket
.EE

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

.EX
podman system service --time 5
.EE

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

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

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

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

.SH "همچنین ببینید (SEE ALSO)"
\fBpodman(1)\fP, \fBpodman-system-connection(1)\fP, \fBcontainers.conf(5)\fP

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