| IMPORTCTL(1) | importctl | IMPORTCTL(1) |
نام (NAME)
importctl - دانلود، واردسازی و صادر کردن ایمیجهای دیسک و ماشین مجازی
خلاصه دستور (SYNOPSIS)
importctl [OPTIONS...] {COMMAND} [NAME...]
توضیحات (DESCRIPTION)
دستور importctl ممکن است برای دانلود، واردسازی و صادر کردن ایمیجهای دیسک از طریق systemd-importd.service(8) استفاده شود.
دستور importctl هم بر روی ایمیجهای دیسک در سطح بلوک (مانند DDIها)، ایمیجهای در سطح سیستمفایل (tarballها) و هم بر روی ایمیجهای OCI عمل میکند. این دستور از ایمیجهای دیسک در یکی از چهار رده (class) زیر پشتیبانی میکند:
هنگامی که ایمیجها دانلود یا وارد میشوند، بسته به پارامتر --class= در دایرکتوریهای زیر قرار میگیرند:
جدول ۱. ردهها و دایرکتوریها
| رده (Class) | دایرکتوری (Directory) |
| "machine" | /var/lib/machines/ |
| "portable" | /var/lib/portables/ |
| "sysext" | /var/lib/extensions/ |
| "confext" | /var/lib/confexts/ |
دستورات (COMMANDS)
دستورات
زیر
پشتیبانی
میشوند:
pull-tar URL [NAME]
ایمیج پیش از آنکه در دسترس قرار گیرد اعتبارسنجی میشود، مگر اینکه --verify=no مشخص شده باشد. اعتبارسنجی یا از طریق فایلی با نام ایمیج و پسوند .sha256 و یک امضای جداگانه (detached) .sha256.asc یا .sha256.gpg انجام میشود، یا از طریق فایلهای مجزای SHA256SUMS و SHA256SUMS.asc یا SHA256SUMS.gpg. فایلهای امضا باید بر روی همان وبسرور و تحت همان URL فایل .tar در دسترس قرار گیرند. با --verify=checksum، تنها چکسام SHA256 فایل بر اساس فایل دارای پسوند .sha256 یا فایل SHA256SUMS اعتبارسنجی میشود. با --verify=signature، ابتدا فایل چکسام sha با امضای جداگانه GPG مربوط به .sha256 یا SHA256SUMS اعتبارسنجی میگردد. کلید عمومی برای این مرحله اعتبارسنجی باید در /usr/lib/systemd/import-pubring.pgp یا /etc/systemd/import-pubring.pgp موجود باشد.
در صورتی که --keep-download=yes مشخص شده باشد، ایمیج دانلود شده و در یک زیرحجم (subvolume)/دایرکتوری فقطخواندنی در دایرکتوری ایمیج که بر اساس URL مشخصشده و ETag پروتکل HTTP آن نامگذاری میشود، ذخیره میگردد (برای اطلاعات بیشتر به HTTP ETag[1] مراجعه کنید). سپس یک اسنپشات قابلنوشتن از این زیرحجم گرفته شده و به نام محلی مشخصشده نامگذاری میشود. این رفتار تضمین میکند که ایجاد چندین نمونه از یک URL با راندمان بالا صورت گیرد، زیرا نیازی به چندین بار دانلود نخواهد بود. به منظور ایجاد تنها ایمیج فقطخواندنی، و جلوگیری از ایجاد اسنپشات قابلنوشتن آن، مقدار "-" را به عنوان نام محلی مشخص کنید.
توجه داشته باشید که فشردن Control-c در حین اجرای این دستور باعث لغو دانلود نخواهد شد. از cancel-transfer که در زیر شرح داده شده است استفاده کنید.
افزودهشده در نسخه 256.
pull-raw URL [NAME]
اعتبارسنجی ایمیج برای ایمیجهای raw و tar یکسان است (به بالا مراجعه کنید).
اگر ایمیج دانلودشده در قالب qcow2 باشد، پیش از در دسترس قرار گرفتن به یک فایل ایمیج raw تبدیل میشود.
در صورتی که --keep-download=yes مشخص شده باشد، ایمیج دانلود شده و در یک فایل فقطخواندنی در دایرکتوری ایمیج که بر اساس URL مشخصشده و ETag پروتکل HTTP آن نامگذاری شده است ذخیره میشود. سپس یک رونوشت قابلنوشتن از این فایل ساخته شده و با نام محلی مشخصشده نامگذاری میگردد. این رفتار تضمین میکند که ایجاد چندین نمونه از یک URL با کارایی بالا صورت گیرد، زیرا نیازی به چندین بار دانلود نخواهد بود. برای ایجاد تنها ایمیج فقطخواندنی، و اجتناب از ایجاد رونوشت قابلنوشتن آن، مقدار "-" را به عنوان نام محلی مشخص کنید.
توجه داشته باشید که فشردن Control-c در حین اجرای این دستور دانلود را متوقف نخواهد کرد. از cancel-transfer که در زیر توضیح داده شده استفاده کنید.
افزودهشده در نسخه 256.
pull-oci REF [NAME]
هنگام دانلود ایمیجهای این نوع، هیچ اعتبارسنجی ایمیجی فراتر از احراز هویت معمول گواهیهای HTTPS انجام نمیشود.
توجه داشته باشید که فشردن Control-c در حین اجرای این دستور دانلود را لغو نخواهد کرد. از cancel-transfer که در زیر شرح داده شده استفاده کنید.
افزودهشده در نسخه 260.
import-tar FILE [NAME], import-raw FILE [NAME]
هنگام وارد کردن ایمیجها هیچ اعتبارسنجی رمزنگاریشدهای انجام نمیشود.
همانند دانلود ایمیجها، فرآیندهای واردسازی در حال اجرا نیز میتوانند با list فهرست شده و با cancel-transfer لغو شوند.
افزودهشده در نسخه 256.
import-fs DIRECTORY [NAME]
افزودهشده در نسخه 256.
export-tar NAME [FILE], export-raw NAME [FILE]
مشابه دانلودها و واردسازیهای ایمیج، صادراتهای در حال انجام را نیز میتوان با list فهرست کرده و با cancel-transfer لغو نمود.
توجه داشته باشید که در حال حاضر، تنها ایمیجهای دایرکتوری و زیرحجم میتوانند به عنوان ایمیجهای TAR، و تنها ایمیجهای دیسک خام به عنوان ایمیجهای RAW صادر شوند.
افزودهشده در نسخه 256.
list-transfer
افزودهشده در نسخه 256.
cancel-transfer ID...
افزودهشده در نسخه 256.
list-images
افزودهشده در نسخه 256.
گزینهها (OPTIONS)
گزینههای زیر پشتیبانی میشوند:
--read-only
افزودهشده در نسخه 256.
--verify=
افزودهشده در نسخه 256.
--force
افزودهشده در نسخه 256.
--format=
افزودهشده در نسخه 256.
-q, --quiet
افزودهشده در نسخه 256.
-H, --host=
-M, --machine=
افزودهشده در نسخه 256.
--class=, -m, -P, -S, -C
توجه داشته باشید که --keep-download= برای --class=machine بهطور پیشفرض true و در غیر این صورت false است، به زیر مراجعه کنید.
افزودهشده در نسخه 256.
--keep-download=, -N
سوییچ -N میانبری برای --keep-download=no است.
افزودهشده در نسخه 256.
--json=MODE
-j
--no-pager
--no-legend
--no-ask-password
-h, --help
--version
مثالها (EXAMPLES)
مثال ۱. دانلود یک ایمیج TAR اوبونتو و باز کردن یک پوسته در آن
# importctl pull-tar -mN https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64-root.tar.xz # systemd-nspawn -M jammy-server-cloudimg-amd64-root
این دستور ایمیج .tar مشخصشده را دانلود و اعتبارسنجی میکند، و سپس از systemd-nspawn(1) برای باز کردن یک پوسته در آن استفاده مینماید.
مثال ۲. دانلود یک ایمیج RAW اوبونتو، تنظیم گذرواژه ریشه در آن، و شروع آن به عنوان یک سرویس
# importctl pull-raw -mN \
https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64-disk-kvm.img \
jammy
# systemd-firstboot --image=/var/lib/machines/jammy.raw --prompt-root-password --force
# machinectl start jammy
# machinectl login jammy
این دستور ایمیج .raw مشخصشده را دانلود کرده و آن را تحت نام محلی "jammy" در دسترس قرار میدهد. سپس با systemd-firstboot(1) یک گذرواژه ریشه تنظیم میشود. پس از آن، ماشین به عنوان یک سرویس سیستم شروع به کار میکند. با آخرین دستور، اعلان ورود به داخل کانتینر درخواست میشود.
مثال ۳. صادر کردن یک ایمیج کانتینر به عنوان فایل tar
# importctl export-tar -m fedora myfedora.tar.xz
کانتینر "fedora" را به عنوان یک فایل tar فشردهشده با xz به نام myfedora.tar.xz در دایرکتوری جاری صادر میکند.
کدهای خروج (EXIT STATUS)
در صورت موفقیت 0 بازگردانده میشود، و در غیر این صورت یک کد شکست غیرصفر بازگردانده خواهد شد.
محیط (ENVIRONMENT)
$SYSTEMD_LOG_LEVEL
$SYSTEMD_LOG_COLOR
این تنظیم تنها زمانی مفید است که پیامها مستقیماً در ترمینال نوشته شوند، زیرا journalctl(1) و سایر ابزارهایی که لاگها را نمایش میدهند پیامها را خودشان بر اساس سطح لاگ رنگآمیزی میکنند.
$SYSTEMD_LOG_TIME
این تنظیم تنها زمانی مفید است که پیامها مستقیماً در ترمینال یا یک فایل نوشته شوند، زیرا journalctl(1) و سایر ابزارهایی که لاگها را نمایش میدهند برچسبهای زمانی را خودشان بر اساس فرادادههای مدخل پیوست میکنند.
$SYSTEMD_LOG_LOCATION
توجه داشته باشید که مکان لاگ اغلب به هر حال به عنوان فراداده به مدخلهای ژورنال پیوست میشود. با این حال گنجاندن مستقیم آن در متن پیام میتواند هنگام اشکالزدایی برنامهها بسیار سودمند باشد.
$SYSTEMD_LOG_TID
توجه داشته باشید که این اطلاعات به هر حال به عنوان فراداده به مدخلهای ژورنال پیوست میشود. با این حال گنجاندن مستقیم آن در متن پیام میتواند هنگام اشکالزدایی برنامهها سودمند باشد.
$SYSTEMD_LOG_TARGET
$SYSTEMD_LOG_RATELIMIT_KMSG
$SYSTEMD_PAGER, $PAGER
نکته: اگر $SYSTEMD_PAGERSECURE تنظیم نشده باشد، $SYSTEMD_PAGER و $PAGER تنها میتوانند برای غیرفعال کردن صفحهبند (با "cat" یا "") استفاده شوند و در غیر این صورت نادیده گرفته میشوند.
$SYSTEMD_LESS
کاربران ممکن است به ویژه مایل به تغییر دو گزینه باشند:
K
اگر مقدار $SYSTEMD_LESS شامل "K" نباشد، و صفحهبند فراخوانیشده less باشد، Ctrl+C توسط برنامه اجرایی نادیده گرفته شده و باید توسط صفحهبند مدیریت شود.
X
توجه داشته باشید که تنظیم متغیر محیطی معمولی $LESS هیچ اثری بر فراخوانیهای less توسط ابزارهای systemd ندارد.
برای بررسی بیشتر به less(1) مراجعه کنید.
$SYSTEMD_LESSCHARSET
توجه داشته باشید که تنظیم متغیر محیطی معمولی $LESSCHARSET هیچ اثری بر فراخوانیهای less توسط ابزارهای systemd ندارد.
$SYSTEMD_PAGERSECURE
این گزینه یک آرگومان بولی میپذیرد. در صورت تنظیم روی true، «حالت امن» صفحهبند فعال میشود. در «حالت امن»، هنگام فراخوانی صفحهبند متغیر LESSSECURE=1 تنظیم خواهد شد که به صفحهبند دستور میدهد دستوراتی را که فایلهای جدید باز میکنند یا میسازند، یا زیرپردازشهای جدید را آغاز مینمایند، غیرفعال کند. در حال حاضر تنها less(1) شناخته شده است که این متغیر را درک کرده و «حالت امن» را پیادهسازی مینماید.
در صورت تنظیم روی false، هیچ محدودیتی بر صفحهبند اعمال نمیشود. تنظیم SYSTEMD_PAGERSECURE=0 یا حذف نکردن آن از محیط به ارث رسیده ممکن است به کاربر اجازه اجرای دستورات دلخواه را بدهد.
هنگامی که $SYSTEMD_PAGERSECURE تنظیم نشده باشد، ابزارهای systemd تلاش میکنند بهطور خودکار تشخیص دهند که آیا «حالت امن» باید فعال شود و آیا صفحهبند از آن پشتیبانی میکند یا خیر. اگر شناسه کاربری مؤثر (UID) با مالک نشست ورود یکسان نباشد (به geteuid(2) و sd_pid_get_owner_uid(3) مراجعه کنید)، یا هنگام اجرا تحت sudo(8) یا ابزارهای مشابه (که $SUDO_UID تنظیم شده باشد [2])، «حالت امن» فعال میشود. در این حالتها، SYSTEMD_PAGERSECURE=1 تنظیم خواهد شد و صفحهبندهایی که اجرای «حالت امن» توسط آنها شناخته نشده است اصلاً استفاده نخواهند شد. توجه داشته باشید که این تشخیص خودکار تنها متداولترین سازوکارهای ارتقای اختیارات را پوشش میدهد و برای راحتی کار در نظر گرفته شده است. توصیه میشود صراحتاً $SYSTEMD_PAGERSECURE را تنظیم کنید یا صفحهبند را غیرفعال نمایید.
توجه داشته باشید که اگر قرار باشد متغیرهای $SYSTEMD_PAGER یا $PAGER رعایت شوند، به جز برای غیرفعال کردن صفحهبند، باید $SYSTEMD_PAGERSECURE نیز تنظیم شده باشد.
$SYSTEMD_COLORS
true
false
"16", "256", "24bit"
"auto-16", "auto-256", "auto-24bit"
$SYSTEMD_URLIFY
همچنین ببینید (SEE ALSO)
systemd(1), systemd-importd.service(8), systemd-nspawn(1), systemd-vmspawn(1), machinectl(1), portablectl(1), systemd-sysext(8), systemd-confext(8), tar(1), xz(1), gzip(1), zstd(1), bzip2(1)
یادداشتها (NOTES)
- 1.
- HTTP ETag
- 2.
- به سایر ابزارها توصیه میشود متناسب با نیاز، $SUDO_UID را تنظیم و بررسی کنند و با آن به عنوان یک رابط مشترک رفتار نمایند.
| systemd 261.2 |