podman-generate-systemd(1) General Commands Manual podman-generate-systemd(1)

podman-generate-systemd - [منسوخ‌شده] تولید فایل(های) واحد systemd برای یک کانتینر یا پاد

podman generate systemd [گزینه‌ها] کانتینر|پاد

منسوخ‌شده: نکته: دستور podman generate systemd منسوخ شده است. توصیه می‌کنیم هنگام اجرای کانتینرها یا پادهای پادمن تحت systemd از فایل‌های [Quadlet] استفاده کنید. برنامه‌ای برای حذف این دستور وجود ندارد. این دستور رفع اشکال‌های اضطراری را دریافت خواهد کرد اما هیچ قابلیت جدیدی به آن افزوده نخواهد شد.

دستور podman generate systemd یک فایل واحد systemd ایجاد می‌کند که می‌تواند برای کنترل یک کانتینر یا پاد مورد استفاده قرار گیرد. به طور پیش‌فرض، این دستور محتوای فایل‌های واحد را در خروجی استاندارد (stdout) چاپ می‌کند.

تولید فایل‌های واحد برای یک پاد مستلزم آن است که پاد همراه با یک کانتینر زیرساخت (infra container) ایجاد شده باشد (به --infra=true مراجعه کنید). یک کانتینر زیرساخت در کل طول عمر پاد اجرا می‌شود و از این رو برای مدیریت چرخه حیات واحد اصلی پاد توسط systemd الزامی است.

  • نکته: هنگام استفاده از این دستور با کلاینت راه دور، از جمله ماشین‌های مک و ویندوز (به استثنای WSL2)، فایل‌های واحد تولیدشده را در سیستم راه دور قرار دهید. علاوه بر این، اطمینان حاصل کنید که متغیر محیطی XDG_RUNTIME_DIR مقداردهی شده باشد. در صورت تنظیم نبودن، آن را با دستور export XDG_RUNTIME_DIR=/run/user/$(id -u) تنظیم کنید.
  • نکته: دستور تولیدشده podman run شامل گزینه --sdnotify با مقداری برگرفته از کانتینر است. اگر کانتینر مقدار مشخصی نداشته باشد یا مقدار آن روی ignore تنظیم شده باشد، مقدار conmon استفاده می‌شود. دلیل بازنویسی مقدار پیش‌فرض container این است که تقریباً هیچ‌یک از بارهای کاری کانتینر پیام‌های اطلاع‌رسانی ارسال نمی‌کنند. اگر از مقدار container برای کانتینری استفاده شود که پیام اعلان نمی‌فرستد، systemd منتظر پیام آماده‌باش می‌ماند که هرگز ارسال نخواهد شد. ممکن است استفاده از مقدار پیش‌فرض بدون قصد قبلی کاربر رخ داده باشد، از این رو مقدار پیش‌فرض بازنویسی شده است.

یک فایل YAML کوبرنتیز را می‌توان از طریق قالب systemd به نام podman-kube@.service در systemd اجرا کرد. آرگومان این قالب مسیر فایل YAML است. با فرض وجود فایل workload.yaml در دایرکتوری خانگی، می‌توان آن را به شکل زیر اجرا نمود:

$ escaped=$(systemd-escape ~/workload.yaml)
$ systemctl --user start podman-kube@$escaped.service
$ systemctl --user is-active podman-kube@$escaped.service
active

افزودن گزینه بعد از (After=) به واحد systemd، که ترتیب وابستگی‌ها را میان فهرست وابستگی‌ها و این سرویس تعیین می‌کند. این گزینه می‌تواند بیش از یک بار مشخص شود.

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

تنظیم پیشوند نام واحد systemd برای کانتینرها. پیش‌فرض container است.

تنظیم متغیرهای محیطی در فایل‌های واحد systemd.

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

تولید فایل به جای چاپ در خروجی استاندارد. فایل‌های تولیدشده با الگوی {container,pod}-{ID,name}.service نام‌گذاری شده و در دایرکتوری کاری فعلی قرار می‌گیرند.

نکته: در سامانه‌ای با SELinux فعال، فایل‌های تولیدشده بافت‌های امنیتی را از دایرکتوری کاری فعلی به ارث می‌برند. بسته به پیکربندی SELinux، ممکن است تغییر فایل‌های تولیدشده با استفاده از restorecon، chcon، یا semanage برای دسترسی systemd به این فایل‌ها لازم باشد. به عنوان راهکار دیگر، هنگام اجرای mv یا cp از گزینه -Z استفاده کنید.

چاپ واحدهای ایجادشده در قالب مشخص‌شده (json). اگر گزینه --files مشخص شده باشد، مسیر فایل‌های ایجادشده به جای محتوای واحد چاپ می‌شود.

استفاده از نام کانتینر برای شروع، توقف و توضیحات در فایل واحد.

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

توجه داشته باشید که --new تنها بر روی کانتینرها و پادهایی کار می‌کند که مستقیماً از طریق پادمن ایجاد شده‌اند (یعنی podman [container] {create,run} یا podman pod create). این گزینه بر روی کانتینرها یا پادهای ایجادشده از طریق REST API یا از طریق podman kube play کار نمی‌کند. برای podman kube play، به جای آن از قالب systemd به نام podman-kube@.service استفاده کنید.

عدم تولید سرآیند شامل فراداده‌هایی مانند نسخه پادمن و برچسب زمانی.

تنظیم پیشوند نام واحد systemd برای پادها. مقدار پیش‌فرض pod است.

تنظیم گزینه نیازمندی‌های واحد systemd (Requires=). شبیه به wants است، اما وابستگی الزامی قوی‌تری را اعلام می‌کند.

تنظیم خط‌مشی راه‌اندازی مجدد در systemd. خط‌مشی باید یکی از موارد زیر باشد: "no"، "on-success"، "on-failure"، "on-abnormal"، "on-watchdog"، "on-abort"، یا "always". خط‌مشی پیش‌فرض on-failure است، مگر اینکه کانتینر با خط‌مشی راه‌اندازی مجدد سفارشی ایجاد شده باشد.

توجه داشته باشید که تولید یک واحد بدون --new بر روی کانتینری با خط‌مشی راه‌اندازی مجدد سفارشی می‌تواند هنگام خاموش شدن سیستم منجر به بروز مشکل شود؛ زیرا systemd تلاش می‌کند واحد را متوقف کند در حالی که پادمن سعی در راه‌اندازی مجدد آن دارد. توصیه می‌شود کانتینر بدون --restart ایجاد شده و از گزینه --restart-policy هنگام تولید فایل واحد استفاده شود.

تنظیم مقدار RestartSec سرویس در systemd. مدت‌زمان توقف پیش از راه‌اندازی مجدد یک سرویس را پیکربندی می‌کند (همان‌گونه که با restart-policy تنظیم شده است). مقداری بر حسب ثانیه می‌گیرد.

تنظیم جداکننده نام واحد systemd بین نام/شناسه کانتینر/پاد و پیشوند. مقدار پیش‌فرض - است.

بازنویسی مهلت زمانی شروع پیش‌فرض برای کانتینر با مقدار داده‌شده بر حسب ثانیه.

بازنویسی مهلت زمانی توقف پیش‌فرض برای کانتینر با مقدار داده‌شده بر حسب ثانیه.

افزودن مشخص‌کننده‌های قالب برای اجرای چندین سرویس از روی فایل واحد systemd.

توجه داشته باشید که اگر --new روی true تنظیم نشده باشد، به طور پیش‌فرض روی true تنظیم می‌شود. با این حال، اگر --new به طور صریح روی false تنظیم شود، دستور با خطا مواجه خواهد شد.

افزودن گزینه خواسته‌ها (Wants=) به واحد systemd که این سرویس وابستگی (ضعیف) به آن دارد. این گزینه می‌تواند بیش از یک بار مشخص شود. این گزینه ترتیبی را که سرویس‌ها در آن شروع یا متوقف می‌شوند تحت تأثیر قرار نمی‌دهد.

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

تولید یک فایل واحد systemd برای یک کانتینر مجری nginx با خط‌مشی راه‌اندازی مجدد always و مهلت ۱ ثانیه در خروجی استاندارد. توجه داشته باشید که گزینه RequiresMountsFor در بخش Unit تضمین می‌کند فضای ذخیره‌سازی کانتینر برای هر دو مسیر GraphRoot و RunRoot قبل از شروع سرویس سوار (mount) شده باشد. در سامانه‌هایی با ذخیره‌سازی کانتینر بر روی دیسک‌هایی نظیر iSCSI یا سایر پروتکل‌های بلوکی راه دور، این گزینه اطمینان می‌دهد پادمن پیش از در دسترس قرار گرفتن عملیات ذخیره‌سازی لازم اجرا نشود.

$ podman create --name nginx nginx:latest
$ podman generate systemd --restart-policy=always -t 1 nginx
# container-de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6.service
# autogenerated by Podman 1.8.0
# Wed Mar 09 09:46:45 CEST 2020
[Unit]
Description=Podman container-de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6.service
Documentation=man:podman-generate-systemd(1)
Wants=network-online.target
After=network-online.target
RequiresMountsFor=/var/run/container/storage
[Service]
Restart=always
ExecStart=/usr/bin/podman start de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6
ExecStop=/usr/bin/podman stop   
        -t 1 de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6
KillMode=none
Type=forking
PIDFile=/run/user/1000/overlay-containers/de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6/userdata/conmon.pid
[Install]
WantedBy=default.target

پرچم --new فایل‌های واحد systemd را به گونه‌ای تولید می‌کند که در دستورات شروع و توقف سرویس، کانتینرها را ایجاد و حذف نمایند (به اقدامات سرویس در ExecStartPre و ExecStopPost مراجعه کنید). چنین فایل‌های واحدی وابسته به یک ماشین خاص نیستند و می‌توان به سادگی آن‌ها را به اشتراک گذاشت و در سایر ماشین‌ها استفاده کرد.

$ sudo podman generate systemd --new --files --name bb310a0780ae
# container-busy_moser.service
# autogenerated by Podman 1.8.3
# Fri Apr  3 09:40:47 EDT 2020
[Unit]
Description=Podman container-busy_moser.service
Documentation=man:podman-generate-systemd(1)
Wants=network-online.target
After=network-online.target
RequiresMountsFor=/var/run/container/storage
[Service]
Environment=PODMAN_SYSTEMD_UNIT=%n
Restart=on-failure
ExecStartPre=/bin/rm -f %t/%n-pid %t/%n-cid
ExecStart=/usr/local/bin/podman run   
        --conmon-pidfile %t/%n-pid   
	--cidfile %t/%n-cid   
	--cgroups=no-conmon   
	-d   
	-dit alpine
ExecStop=/usr/local/bin/podman stop   
        --ignore   
        --cidfile %t/%n-cid -t 10
ExecStopPost=/usr/local/bin/podman rm   
        --ignore   
        -f   
	--cidfile %t/%n-cid
PIDFile=%t/%n-pid
KillMode=none
Type=forking
[Install]
WantedBy=default.target

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

برای بررسی فایل‌های واحد کانتینر یا پاد از systemctl status یا journalctl استفاده کنید.

$ podman pod create --name systemd-pod
$ podman create --pod systemd-pod alpine top
$ podman create --pod systemd-pod alpine top
$ podman generate systemd --files --name systemd-pod
/home/user/pod-systemd-pod.service
/home/user/container-amazing_chandrasekhar.service
/home/user/container-jolly_shtern.service
$ cat pod-systemd-pod.service
# pod-systemd-pod.service
# autogenerated by Podman 1.8.0
# Wed Mar 09 09:52:37 CEST 2020
[Unit]
Description=Podman pod-systemd-pod.service
Documentation=man:podman-generate-systemd(1)
Requires=container-amazing_chandrasekhar.service container-jolly_shtern.service
Before=container-amazing_chandrasekhar.service container-jolly_shtern.service
Wants=network-online.target
After=network-online.target
RequiresMountsFor=/var/run/container/storage
[Service]
Restart=on-failure
ExecStart=/usr/bin/podman start 77a818221650-infra
ExecStop=/usr/bin/podman stop   
        -t 10 77a818221650-infra
KillMode=none
Type=forking
PIDFile=/run/user/1000/overlay-containers/ccfd5c71a088768774ca7bd05888d55cc287698dde06f475c8b02f696a25adcd/userdata/conmon.pid
[Install]
WantedBy=default.target

فایل‌های واحد تولیدشده توسط پادمن شامل بخش [Install] هستند که اطلاعات نصب واحد را در بر دارد. این بخش توسط دستورات enable و disable در systemctl(1) هنگام نصب مورد استفاده قرار می‌گیرد.

پس از تولید فایل واحد systemd، آن را برای اجرا توسط کاربر ریشه (root) در /etc/systemd/system و برای نصب به عنوان کاربر غیرریشه در $HOME/.config/systemd/user قرار دهید. فایل یا فایل‌های کپی‌شده را با استفاده از systemctl enable فعال کنید.

نکته: کپی کردن فایل‌های واحد در /etc/systemd/system و فعال‌سازی آن باعث می‌شود فایل واحد به طور خودکار هنگام بالا آمدن سیستم (boot) آغاز به کار کند. به همین ترتیب، کپی کردن فایل واحد در $HOME/.config/systemd/user و فعال‌سازی آن باعث شروع خودکار واحد هنگام ورود کاربر به سیستم خواهد شد.

# Generated systemd files.
$ podman pod create --name systemd-pod
$ podman create --pod systemd-pod alpine top
$ podman generate systemd --files --name systemd-pod
# Copy all the generated files.
$ sudo cp pod-systemd-pod.service container-great_payne.service /etc/systemd/system
$ systemctl enable pod-systemd-pod.service
Created symlink /etc/systemd/system/multi-user.target.wants/pod-systemd-pod.service → /etc/systemd/system/pod-systemd-pod.service.
Created symlink /etc/systemd/system/default.target.wants/pod-systemd-pod.service → /etc/systemd/system/pod-systemd-pod.service.
$ systemctl is-enabled pod-systemd-pod.service
enabled

برای اجرای سرویس‌های کاربری قرارگرفته در $HOME/.config/systemd/user در نخستین ورود آن کاربر، سرویس را با پرچم --user فعال کنید:

$ systemctl --user enable <.service>

نمونه کاربری systemd پس از بسته شدن آخرین نشست کاربر متوقف می‌شود. می‌توان نمونه کاربری systemd را با فعال‌سازی ماندگاری (lingering) هنگام بوت سیستم آغاز کرد و حتی پس از خروج کاربر فعال نگه داشت:

$ loginctl enable-linger <username>

با استفاده از مثال‌های بالا به عنوان مرجع، فایل‌های واحد systemd را برای یک پاد ایجاد و فعال کنید و از systemctl برای انجام عملیات بهره ببرید.

از آنجا که systemctl به طور پیش‌فرض با کاربر ریشه کار می‌کند، تمامی تغییرات اعمال‌شده از طریق systemctl با افزودن sudo به دستورات پادمن قابل مشاهده است. برای انجام اقدامات systemctl به عنوان کاربر غیرریشه، هنگام کار با systemctl از پرچم --user استفاده کنید.

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

$ systemctl --user start pod-systemd-pod.service
$ podman pod ps
POD ID         NAME          STATUS    CREATED          # OF CONTAINERS   INFRA ID
0815c7b8e7f5   systemd-pod   Running   29 minutes ago   2                 6c5d116f4bbe
$ sudo podman ps # 0 Number of pods on root.
CONTAINER ID  IMAGE  COMMAND  CREATED  STATUS  PORTS  NAMES
$ systemctl stop pod-systemd-pod.service
$ podman pod ps
POD ID         NAME          STATUS   CREATED          # OF CONTAINERS   INFRA ID
272d2813c798   systemd-pod   Exited   29 minutes ago   2                 6c5d116f4bbe

ایجاد یک کانتینر ساده alpine و تولید فایل واحد systemd با پرچم --new: فعال‌سازی سرویس و کنترل عملیات با استفاده از دستورات systemctl.

نکته: هنگام شروع کانتینر با استفاده از systemctl start، به جای دست‌کاری کانتینر در حال اجرا، یک کانتینر "جدید" با پیکربندی مشابه ایجاد و راه‌اندازی می‌شود.

# Enable the service.
$ sudo podman ps -a
CONTAINER ID  IMAGE                            COMMAND  CREATED        STATUS     PORTS  NAMES
bb310a0780ae  docker.io/library/alpine:latest  /bin/sh  2 minutes ago  Created           busy_moser
$ sudo systemctl start container-busy_moser.service
$ sudo podman ps -a
CONTAINER ID  IMAGE                            COMMAND  CREATED        STATUS        PORTS      NAMES
772df2f8cf3b  docker.io/library/alpine:latest  /bin/sh  1 second ago   Up 1 second              distracted_albattani
bb310a0780ae  docker.io/library/alpine:latest  /bin/sh  3 minutes ago  Created                  busy_moser

podman(1), podman-container(1), systemctl(1), systemd.unit(5), systemd.service(5), conmon(8), podman-systemd.unit(5)

آوریل ۲۰۲۰، به‌روزرسانی جزئیات و افزودن مورد کاربرد برای استفاده از فایل‌های service. تولیدشده به عنوان کاربر ریشه (root) و غیرریشه، توسط Sujil Shah (sushah at redhat dot com)

اوت ۲۰۱۹، به‌روزرسانی با پشتیبانی از پاد توسط Valentin Rothberg (rothberg at redhat dot com)

آوریل ۲۰۱۹، در ابتدا توسط Brent Baude گردآوری شد (bbaude at redhat dot com)