virt-customize(1) Virtualization Support virt-customize(1)

virt-customize - سفارشی‌سازی یک ماشین مجازی

virt-customize
   [ -a disk.img [ -a disk.img ... ] | -d domname ]
   [--attach ISOFILE] [--attach-format FORMAT]
   [ -c URI | --connect URI ] [ -n | --dry-run ]
   [ --format FORMAT] [ -m MB | --memsize MB ]
   [ --network | --no-network ]
   [ -q | --quiet ] [--smp N] [ -v | --verbose ] [-x]
   [--append-line FILE:LINE] [--chmod PERMISSIONS:FILE]
   [--chown UID:GID:PATH] [--commands-from-file FILENAME]
   [--copy SOURCE:DEST] [--copy-in LOCALPATH:REMOTEDIR]
   [--delete PATH] [--edit FILE:EXPR] [--firstboot SCRIPT]
   [--firstboot-command 'CMD+ARGS'] [--firstboot-install PKG,PKG..]
   [--hostname HOSTNAME] [--inject-blnsvr METHOD]
   [--inject-qemu-ga METHOD] [--inject-virtio-win METHOD]
   [--install PKG,PKG..] [--link TARGET:LINK[:LINK..]] [--mkdir DIR]
   [--move SOURCE:DEST] [--password USER:SELECTOR]
   [--root-password SELECTOR] [--run SCRIPT]
   [--run-command 'CMD+ARGS'] [--scrub FILE]
   [--ssh-inject USER[:SELECTOR]] [--tar-in TARFILE:REMOTEDIR]
   [--timezone TIMEZONE] [--touch FILE] [--truncate FILE]
   [--truncate-recursive PATH] [--uninstall PKG,PKG..] [--update]
   [--upload FILE:DEST] [--write FILE:CONTENT] [--no-logfile]
   [--password-crypto md5|sha256|sha512] [--no-selinux-relabel]
   [--selinux-relabel]
virt-customize [ -V | --version ]

استفاده از "virt-customize" روی ماشین‌های مجازی در حال اجرا، یا به صورت همزمان با سایر ابزارهای ویرایش دیسک می‌تواند خطرناک باشد و به خرابی داده‌های دیسک منجر شود. ماشین مجازی باید پیش از استفاده از این دستور خاموش شده باشد، و ایمیج‌های دیسک نباید به طور همزمان ویرایش شوند.

ابزار virt-customize می‌تواند یک ماشین مجازی (ایمیج دیسک) را با نصب بسته‌ها، ویرایش فایل‌های پیکربندی و کارهای دیگر سفارشی‌سازی کند.

ابزار virt-customize مهمان یا ایمیج دیسک را درجا (in place) تغییر می‌دهد. سیستم مهمان باید خاموش باشد. اگر می‌خواهید محتویات موجود مهمان حفظ شود، باید ابتدا از دیسک اسنپ‌شات بگیرید، کپی کنید یا آن را کلون نمایید.

شما نیازی ندارید که virt-customize را با دسترسی ریشه (root) اجرا کنید. در واقع ما عموماً توصیه می‌کنیم که آن را با کاربر ریشه اجرا نکنید.

ابزارهای مرتبط عبارتند از: virt-sysprep(1) و virt-builder(1).

نمایش راهنمای مختصر.
افزودن file که باید یک ایمیج دیسک از یک ماشین مجازی باشد.

قالب ایمیج دیسک به صورت خودکار تشخیص داده می‌شود. برای لغو این رفتار و تحمیل یک قالب خاص از گزینه --format استفاده کنید.

افزودن یک دیسک دوردست (remote). قالب شناسه URI با guestfish سازگار است. بخش "ADDING REMOTE STORAGE" را در guestfish(1) ببینید.
دیسک مشخص‌شده به اپلاینس libguestfs متصل (attach) می‌شود. این ویژگی برای ارائه مخازن نرم‌افزاری اضافی یا سایر داده‌ها جهت سفارشی‌سازی استفاده می‌شود.

احتمالاً می‌خواهید مطمئن شوید که حجم(ها) یا سیستم‌های فایل در دیسک‌های متصل‌شده دارای برچسب (label) باشند (یا از نام حجم ISO استفاده کنید) تا بتوانید آن‌ها را بر اساس برچسب در اسکریپت‌های اجرایی خود سوار (mount) کنید:

mkdir /tmp/mount
mount LABEL=EXTRA /tmp/mount

می‌توانید از چندین گزینه --attach استفاده کنید، و قالب آن می‌تواند هر قالب دیسکی باشد (نه فقط ISO).

تعیین قالب دیسک برای گزینه بعدی --attach. مقدار "FORMAT" معمولاً "raw" یا "qcow2" است. برای فایل‌های ISO از "raw" استفاده کنید.
استفاده از دنباله‌های رنگی ANSI برای رنگی کردن پیام‌ها. این حالت در صورتی که خروجی یک tty باشد پیش‌فرض است. اگر خروجی برنامه به یک فایل هدایت شود، دنباله‌های رنگی ANSI غیرفعال می‌شوند مگر اینکه از این گزینه استفاده کنید.
در صورت استفاده از libvirt، به URI داده‌شده متصل می‌شود. در صورت حذف، به هایپروایزر پیش‌فرض libvirt متصل می‌شویم.

اگر دستگاه‌های بلوکی مهمان را مستقیماً مشخص کنید (-a)، آن‌گاه libvirt اصلاً استفاده نمی‌شود.

افزودن تمام دیسک‌های مربوط به مهمان نام‌برده‌شده در libvirt. می‌توان از شناسه UUID دامنه نیز به جای نام استفاده کرد.
انجام یک اجرای آزمایشی و فقط‌خواندنی ("dry run") روی مهمان. این کار عملیات sysprep را اجرا می‌کند، اما در پایان هرگونه تغییر اعمال‌شده روی دیسک را دور می‌ریزد.
هنگام درخواست کلیدها و عبارات عبور، virt-customize به طور معمول بازتاب کاراکترها (echoing) را خاموش می‌کند تا نتوانید آنچه را تایپ می‌کنید ببینید. اگر نگران حملات تمپست (Tempest) نیستید و شخص دیگری در اتاق حضور ندارد، می‌توانید این گزینه را مشخص کنید تا آنچه را تایپ می‌کنید ببینید.
پیش‌فرض برای گزینه -a تشخیص خودکار قالب ایمیج دیسک است. استفاده از این گزینه، قالب دیسک را برای گزینه‌های بعدی -a در خط فرمان تحمیل می‌کند. استفاده از --format auto برای گزینه‌های بعدی -a به حالت تشخیص خودکار بازمی‌گردد.

برای مثال:

virt-customize --format raw -a disk.img

قالب خام (raw) را بدون تشخیص خودکار برای disk.img اعمال می‌کند.

virt-customize --format raw -a disk.img --format auto -a another.img

قالب خام را برای disk.img تحمیل کرده و برای another.img به تشخیص خودکار بازمی‌گردد.

اگر ایمیج‌های دیسک مهمان غیرقابل‌اعتماد با قالب خام دارید، باید از این گزینه برای تعیین قالب دیسک استفاده کنید. این کار از یک مشکل امنیتی احتمالی با مهمان‌های مخرب جلوگیری می‌کند (CVE-2010-3851).

مشخص کردن کلید برای LUKS، جهت باز کردن خودکار دستگاه LUKS هنگام بازرسی.
مقدار "NAME" نام دستگاه در libguestfs است (مانند "/dev/sda1"). مقدار "UUID" شناسه یکتای دستگاه است. مقدار "all" به معنی امتحان کردن کلید در برابر هر دستگاه رمزگذاری‌شده است.

استفاده از "KEY_STRING" مشخص‌شده به عنوان عبارت عبور.

خواندن عبارت عبور از FILENAME.
تلاش برای باز کردن قفل دستگاه بدون نیاز به عبارت عبور با استفاده از Clevis و از طریق شبکه. لطفاً برای اطلاعات بیشتر پیرامون رمزگذاری دیسک وابسته به شبکه (NBDE)، به بخش "ENCRYPTED DISKS" در guestfs(3) مراجعه کنید.

توجه داشته باشید که اگر چنین گزینه‌ای در خط فرمان وجود داشته باشد، شبکه کاربری QEMU به طور خودکار برای اپلاینس libguestfs فعال خواهد شد.

خواندن پارامترهای کلید یا عبارت عبور از ورودی استاندارد (stdin). حالت پیش‌فرض تلاش برای خواندن عبارت عبور از کاربر از طریق باز کردن /dev/tty است.

اگر چندین دستگاه رمزگذاری‌شده وجود داشته باشد، ممکن است لازم باشد چندین کلید را در ورودی استاندارد مشخص کنید، هر کدام در یک سطر.

تغییر مقدار حافظه اختصاص‌یافته به اسکریپت‌های --run. اگر مشاهده کردید که اسکریپت‌های --run یا گزینه --install با کمبود حافظه مواجه می‌شوند، این مقدار را افزایش دهید.

مقدار پیش‌فرض را می‌توان با این دستور پیدا کرد:

guestfish get-memsize
فعال یا غیرفعال کردن دسترسی مهمان به شبکه در طول فرایند نصب.

فعال بودن حالت پیش‌فرض است. برای غیرفعال کردن دسترسی از --no-network استفاده کنید.

شبکه تنها اجازه برقراری اتصالات خروجی را می‌دهد و محدودیت‌های جزئی دیگری دارد. بخش "NETWORK" را در virt-rescue(1) ببینید.

اگر از --no-network استفاده کنید، برخی گزینه‌های دیگر مانند --install کار نخواهند کرد.

این گزینه بر دسترسی مهمان به شبکه پس از بوت شدن سیستم تاثیری نمی‌گذارد، زیرا آن موضوع توسط هایپروایزر یا محیط ابری شما کنترل می‌شود و ارتباطی با virt-customize ندارد.

به طور کلی شما نباید از --no-network استفاده کنید. اما در اینجا چند دلیل وجود دارد که ممکن است بخواهید از آن استفاده کنید:

1.
چون بستر (backend) مورد استفاده libguestfs از شبکه پشتیبانی نمی‌کند. (ببینید: "BACKEND" در guestfs(3)).
2.
هر نرم‌افزاری که باید نصب کنید از یک فایل ISO متصل‌شده ارائه می‌شود، بنابراین به شبکه نیازی ندارید.
3.
شما مایل نیستید کد غیرقابل‌اعتماد مهمان هنگام اجرای virt-customize تلاش کند به شبکه میزبان شما دسترسی پیدا کند. این موضوع به ویژه زمانی اهمیت دارد که به منبع الگوهای سیستم‌عامل اطمینان ندارید. (بخش "امنیت" را در ادامه ببینید).
4.
میزبان شما شبکه ندارد (مثلاً در محیط‌های امنیتی/محدودشده).
پیام‌های لاگ چاپ نشوند.

برای فعال کردن لاگ تفصیلی عملیات تک‌تک فایل‌ها، از -x استفاده کنید.

فعال کردن N ≥ 2 پردازنده مجازی (vCPU) برای استفاده توسط اسکریپت‌های --run.
فعال کردن پیام‌های با جزئیات کامل جهت اشکال‌زدایی.
نمایش شماره نسخه و خروج.
شکستن خطوط پیام‌های خطا، هشدار و اطلاعاتی. این حالت در صورتی که خروجی یک tty باشد پیش‌فرض است. اگر خروجی برنامه به یک فایل هدایت شود، شکستن خطوط غیرفعال می‌شود مگر اینکه از این گزینه استفاده کنید.
فعال کردن ردیابی فراخوانی‌های واسط برنامه‌نویسی (API) libguestfs.

الحاق یک سطر متنی به انتهای "FILE". اگر فایل از قبل با یک خط جدید پایان نیافته باشد، یک خط جدید پیش از سطر الحاقی اضافه می‌شود. همچنین یک خط جدید به صورت خودکار به انتهای رشته "LINE" افزوده می‌شود.

برای مثال (با فرض کوتیشن‌گذاری معمول پوسته) این دستور:

--append-line '/etc/hosts:10.0.0.1 foo'

عبارت "10.0.0.1 foo⏎" یا "⏎10.0.0.1 foo⏎" را به فایل اضافه خواهد کرد، که مورد دوم تنها در صورتی است که فایل موجود قبلاً با یک خط جدید پایان نیافته باشد.

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

برای درج چند سطر، همین گزینه را چند بار استفاده کنید:

--append-line '/etc/hosts:10.0.0.1 foo'
--append-line '/etc/hosts:10.0.0.2 bar'

برای درج یک سطر خالی پیش از سطر الحاقی، این کار را انجام دهید:

--append-line '/etc/hosts:'
--append-line '/etc/hosts:10.0.0.1 foo'
تغییر مجوزهای دسترسی "FILE" به "PERMISSIONS".

نکته: مقدار "PERMISSIONS" به طور پیش‌فرض ده‌دهی خواهد بود، مگر اینکه پیشوند 0 را برای هشت‌هشتی (octal) قرار دهید؛ یعنی از 0700 استفاده کنید نه 700.

تغییر شناسه کاربری (UID) و گروهی (GID) مالک یک فایل یا دایرکتوری در مهمان. نکته:
  • تنها مقادیر عددی UID و GID کار خواهند کرد، و این مقادیر ممکن است در داخل مهمان با مقادیر روی میزبان متفاوت باشند.
  • این گزینه در مهمان‌های ویندوزی کار نخواهد کرد.

برای مثال:

virt-customize --chown '0:0:/var/log/audit.log'

همچنین ببینید: --upload.

خواندن دستورات سفارشی‌سازی از یک فایل، یک دستور (و آرگومان‌های آن) در هر سطر.

هر سطر حاوی یک دستور سفارشی‌سازی تکی و آرگومان‌های آن است، برای مثال:

delete /some/file
install some-package
password some-user:password:its-new-password

سطرهای خالی نادیده گرفته می‌شوند، و سطرهایی که با "#" آغاز می‌شوند کامنت بوده و آن‌ها نیز نادیده گرفته می‌شوند. علاوه بر این، آرگومان‌ها می‌توانند با افزودن یک "\" (کاراکتر ادامه‌دهنده) در انتهای سطر، در چند سطر پخش شوند؛ برای مثال:

edit /some/file:\
  s/^OPT=.*/OPT=ok/

دستورات به همان ترتیبی که در فایل آمده‌اند پردازش می‌شوند، درست مانند اینکه به عنوان --delete /some/file در خط فرمان مشخص شده باشند.

کپی کردن فایل‌ها یا دایرکتوری‌ها به صورت بازگشتی درون مهمان.

نمی‌توان از نویسه‌های عام (wildcards) استفاده کرد.

کپی کردن فایل‌ها یا دایرکتوری‌های محلی به صورت بازگشتی به درون ایمیج دیسک، و قرار دادن آن‌ها در دایرکتوری "REMOTEDIR" (که باید وجود داشته باشد).

نمی‌توان از نویسه‌های عام استفاده کرد.

حذف یک فایل از مهمان، یا حذف یک دایرکتوری (و تمامی محتویات آن، به صورت بازگشتی).

می‌توانید از کاراکترهای الگوی پوسته (glob) در مسیر مشخص‌شده استفاده کنید. مراقب باشید در صورت نیاز، کاراکترهای عمومی را برای پوسته میزبان اسکیپ کنید. برای مثال:

virt-customize --delete '/var/log/*.log'.

همچنین ببینید: --upload، --scrub.

ویرایش "FILE" با استفاده از عبارت پرل "EXPR".

مراقب باشید که عبارت را به درستی کوتیشن‌گذاری کنید تا از تغییر آن توسط پوسته جلوگیری شود.

توجه داشته باشید که این گزینه تنها زمانی در دسترس است که Perl 5 نصب باشد.

بخش "NON-INTERACTIVE EDITING" را در virt-edit(1) ببینید.

نصب "SCRIPT" درون مهمان، تا هنگام نخستین بوت مهمان، اسکریپت (به عنوان کاربر root، در اواخر فرایند بوت) اجرا شود.

اسکریپت پس از نصب در مهمان به طور خودکار با chmod +x قابل‌اجرا می‌شود.

نسخه جایگزین --firstboot-command مشابه است، اما دستور را به راحتی در یک اسکریپت تک‌خطی برای شما قرار می‌دهد.

می‌توانید چندین گزینه --firstboot داشته باشید. آن‌ها به همان ترتیبی که در خط فرمان ظاهر می‌شوند اجرا می‌شوند.

همچنین ببینید: "بوت اولیه (FIRSTBOOT)"، --run.

اجرای دستور (و آرگومان‌ها) درون مهمان هنگامی که مهمان برای نخستین بار بوت می‌شود (به عنوان کاربر root، در اواخر فرایند بوت).

می‌توانید چندین گزینه --firstboot داشته باشید. آن‌ها به همان ترتیبی که در خط فرمان ظاهر می‌شوند اجرا می‌شوند.

همچنین ببینید: "بوت اولیه (FIRSTBOOT)"، --run.

نصب بسته‌های نام‌برده‌شده (فهرستی جداشده با کاما). این بسته‌ها هنگام نخستین بوت مهمان با استفاده از مدیر بسته مهمان (مانند apt، yum و غیره) و اتصال شبکه مهمان نصب می‌شوند.

برای مرور کلی روش‌های مختلف نصب بسته‌ها، بخش "INSTALLING PACKAGES" را در virt-builder(1) ببینید.

تنظیم نام میزبان (hostname) مهمان روی "HOSTNAME". در صورت تمایل می‌توانید از یک نام دامنه کامل نقطه‌دار (FQDN) مانند hostname.domainname استفاده کنید.
تزریق سرور بالون (blnsvr.exe) به یک مهمان ویندوزی. این عملیات همچنین یک اسکریپت بوت اولیه تزریق می‌کند تا سرور بالون هنگام بوت شدن مهمان نصب شود.

پارامتر مشابه پارامتر مورد استفاده در عملیات --inject-virtio-win است.

توجه داشته باشید که برای انجام یک تبدیل کامل برای مهمان ویندوزی از یک هایپروایزر دیگر مانند VMware (که شامل عملیات متعددی است)، باید به جای این گزینه از ابزار virt-v2v(1) استفاده کنید.

تزریق عامل مهمان QEMU (QEMU Guest Agent) به یک مهمان ویندوزی. عامل مهمان از طریق یک سوکت با qemu ارتباط برقرار می‌کند تا ویژگی‌های پیشرفته‌تری ارائه دهد (ببینید: qemu-ga(8)). این عملیات همچنین یک اسکریپت بوت اولیه تزریق می‌کند تا Guest Agent هنگام بوت شدن مهمان نصب شود.

پارامتر مشابه پارامتر مورد استفاده در عملیات --inject-virtio-win است.

توجه داشته باشید که برای انجام یک تبدیل کامل برای مهمان ویندوزی از یک هایپروایزر دیگر مانند VMware (که شامل عملیات متعددی است)، باید به جای این گزینه از ابزار virt-v2v(1) استفاده کنید.

تزریق درایورهای virtio-win به یک مهمان ویندوزی. این درایورها، درایورهای شتاب‌یافته virtio را اضافه می‌کنند که هنگام اجرا بر روی هایپروایزرهای پشتیبانی‌کننده از virtio (مانند qemu/KVM) مناسب هستند. این عملیات همچنین رجیستری ویندوز را تنظیم می‌کند تا درایورها هنگام بوت شدن مهمان نصب شوند.

پارامتر می‌تواند یکی از موارد زیر باشد:

مسیر ایمیج ISO حاوی درایورهای virtio-win (مانند /usr/share/virtio-win/virtio-win.iso).
دایرکتوری حاوی درایورهای استخراج‌شده virtio-win (مانند /usr/share/virtio-win).

توجه داشته باشید که برای انجام یک تبدیل کامل برای مهمان ویندوزی از یک هایپروایزر خارجی مانند VMware (که شامل عملیات متعدد دیگری است)، باید به جای این گزینه از ابزار virt-v2v(1) استفاده کنید.

نصب بسته‌های نام‌برده‌شده (فهرستی جداشده با کاما). این بسته‌ها در طول فرایند ساخت ایمیج با استفاده از مدیر بسته مهمان (مانند apt، yum و غیره) و از طریق اتصال شبکه میزبان نصب می‌شوند.

برای مرور کلی روش‌های گوناگون نصب بسته‌ها، بخش "INSTALLING PACKAGES" را در virt-builder(1) ببینید.

همچنین ببینید: --update، --uninstall.

ایجاد پیوند(های) نمادین درون مهمان، که از "LINK" آغاز شده و به "TARGET" اشاره می‌کنند.
ایجاد یک دایرکتوری در مهمان.

این گزینه از "mkdir -p" استفاده می‌کند، بنابراین دایرکتوری‌های میانی نیز ایجاد می‌شوند، و همچنین در صورتی که دایرکتوری از قبل وجود داشته باشد به درستی عمل می‌کند.

انتقال یا جابه‌جایی فایل‌ها یا دایرکتوری‌ها درون مهمان.

نمی‌توان از نویسه‌های عام استفاده کرد.

پاک‌سازی و امحای "builder.log" (فایل لاگ دستورات ساخت) از ایمیج پس از پایان فرایند ساخت. اگر نمی‌خواهید دقیقاً مشخص شود که ایمیج چگونه ساخته شده است، از این گزینه استفاده کنید.

همچنین ببینید: "فایل لاگ (Log file)".

عدم تلاش برای تصحیح برچسب‌های SELinux فایل‌ها در مهمان.

در مهمان‌هایی که از SELinux پشتیبانی می‌کنند، سفارشی‌سازی به طور خودکار برچسب فایل‌ها را مجدداً تنظیم می‌کند تا دارای برچسب صحیح SELinux باشند. (برچسب‌گذاری مجدد بلافاصله انجام می‌شود، اما اگر عملیات با شکست مواجه شود، فرایند سفارشی‌سازی فایل /.autorelabel را روی ایمیج لمس می‌کند تا عملیات برچسب‌گذاری مجدد را برای بوت بعدی ایمیج زمان‌بندی کند.) این گزینه برچسب‌گذاری مجدد خودکار را غیرفعال می‌کند.

این گزینه برای مهمان‌هایی که از SELinux پشتیبانی نمی‌کنند بی‌اثر است.

تنظیم گذرواژه برای "USER". (توجه داشته باشید که این گزینه حساب کاربری ایجاد نمی‌کند).

بخش "USERS AND PASSWORDS" را در virt-builder(1) برای قالب فیلد "SELECTOR" و همچنین نحوه ایجاد حساب‌های کاربری ببینید.

هنگامی که ابزارهای virt گذرواژه‌ای را در مهمان تغییر داده یا تنظیم می‌کنند، این گزینه الگوریتم رمزنگاری آن گذرواژه را روی "md5"، "sha256" یا "sha512" تعیین می‌کند.

الگوریتم‌های "sha256" و "sha512" نیازمند نسخه glibc ≥ 2.7 هستند (بخش crypt(3) را در داخل مهمان بررسی کنید).

الگوریتم "md5" با مهمان‌های نسبتاً قدیمی لینوکس (مانند RHEL 3) کار می‌کند، اما در برابر حملات امروزی ایمن نیست.

حالت پیش‌فرض "sha512" است مگر اینکه libguestfs یک مهمان قدیمی را شناسایی کند که از SHA-512 پشتیبانی نمی‌کند، که در این حالت از "md5" استفاده خواهد کرد. می‌توانید با مشخص کردن این گزینه، رفتار پیش‌فرض libguestfs را بازنویسی کنید.

توجه داشته باشید که این گزینه الگوریتم رمزنگاری پیش‌فرض استفاده‌شده توسط مهمان را هنگام ایجاد حساب‌های کاربری جدید درون مهمان تغییر نمی‌دهد. اگر می‌خواهید آن را تغییر دهید، باید از گزینه --edit برای ویرایش "/etc/sysconfig/authconfig" (در Fedora و RHEL) یا "/etc/pam.d/common-password" (در Debian و Ubuntu) استفاده کنید.

تنظیم گذرواژه کاربر ریشه (root).

بخش "USERS AND PASSWORDS" را در virt-builder(1) برای قالب فیلد "SELECTOR" و همچنین نحوه ایجاد حساب‌های کاربری ببینید.

نکته: در virt-builder، اگر --root-password را تنظیم نکنید، یک گذرواژه ریشه تصادفی به مهمان اختصاص می‌یابد.

اجرای اسکریپت شل (یا هر برنامه دیگری) با نام "SCRIPT" روی ایمیج دیسک. این اسکریپت به صورت مجازی‌شده درون یک اپلاینس کوچک، و با chroot به سیستم فایل مهمان اجرا می‌شود.

اسکریپت به طور خودکار chmod +x می‌شود.

اگر libguestfs از آن پشتیبانی کند، یک اتصال شبکه محدود در دسترس خواهد بود که تنها اتصالات خروجی شبکه را مجاز می‌داند. همچنین می‌توانید دیسک‌های داده (مانند فایل‌های ISO) را متصل کنید تا راه دیگری برای ارائه داده‌ها (مانند بسته‌های نرم‌افزاری) به اسکریپت بدون نیاز به اتصال شبکه داشته باشید (--attach). همچنین می‌توانید فایل‌های داده را بارگذاری کنید (--upload).

می‌توانید چندین گزینه --run داشته باشید. آن‌ها به همان ترتیبی که در خط فرمان ظاهر می‌شوند اجرا می‌شوند.

همچنین ببینید: --firstboot، --attach، --upload.

اجرای دستور و آرگومان‌ها روی ایمیج دیسک. دستور به صورت مجازی‌شده درون یک اپلاینس کوچک و با chroot به سیستم فایل مهمان اجرا می‌شود.

اگر libguestfs از آن پشتیبانی کند، یک اتصال شبکه محدود در دسترس خواهد بود که تنها اتصالات خروجی شبکه را مجاز می‌داند. همچنین می‌توانید دیسک‌های داده (مانند فایل‌های ISO) را متصل کنید تا راه دیگری برای ارائه داده‌ها (مانند بسته‌های نرم‌افزاری) به اسکریپت بدون نیاز به اتصال شبکه داشته باشید (--attach). همچنین می‌توانید فایل‌های داده را بارگذاری نمایید (--upload).

می‌توانید چندین گزینه --run-command داشته باشید. آن‌ها به همان ترتیبی که در خط فرمان ظاهر می‌شوند اجرا می‌گردند.

همچنین ببینید: --firstboot، --attach، --upload.

امحا و پاک‌سازی امن یک فایل از مهمان. این گزینه شبیه --delete است به جز اینکه:
  • داده‌ها را به طور کامل امحا می‌کند به طوری که مهمان قادر به بازیابی آن نباشد.
  • نمی‌تواند دایرکتوری‌ها را حذف کند، بلکه تنها فایل‌های معمولی را حذف می‌کند.
این یک گزینه سازگاری است که هیچ کاری انجام نمی‌دهد.
تزریق یک کلید SSH به طوری که کاربر "USER" داده‌شده بتواند بدون نیاز به گذرواژه از طریق ssh وارد شود. کاربر "USER" باید از قبل در مهمان وجود داشته باشد.

بخش "SSH KEYS" در virt-builder(1) را برای قالب فیلد "SELECTOR" ببینید.

می‌توانید چندین گزینه --ssh-inject برای کاربران مختلف و همچنین برای افزودن کلیدهای بیشتر برای هر کاربر داشته باشید.

کپی کردن فایل‌ها یا دایرکتوری‌های محلی از یک فایل tar محلی با نام "TARFILE" به درون ایمیج دیسک، و قرار دادن آن‌ها در دایرکتوری "REMOTEDIR" (که باید وجود داشته باشد). توجه داشته باشید که فایل tar باید غیرفشرده باشد (فایل‌های .tar.gz در اینجا کار نخواهند کرد).
تنظیم منطقه زمانی پیش‌فرض مهمان روی "TIMEZONE". از یک رشته مکان مانند "Asia/Tehran" یا "Europe/London" استفاده کنید.
این دستور عملیاتی شبیه به دستور touch(1) را روی "FILE" اجرا می‌کند.
این دستور طول فایل "FILE" را به صفر می‌رساند (خالی می‌کند). فایل باید از قبل وجود داشته باشد.
این دستور به طور بازگشتی طول تمامی فایل‌های زیرمسیر "PATH" را به صفر می‌رساند.
حذف بسته‌های نام‌برده‌شده (فهرستی جداشده با کاما). این بسته‌ها در طول فرایند ساخت ایمیج با استفاده از مدیر بسته مهمان (مانند apt، yum و غیره) حذف می‌شوند. بسته‌های وابسته نیز ممکن است برای برآورده کردن این درخواست حذف شوند.

همچنین ببینید: --install، --update.

انجام معادل دستورات "yum update"، "apt-get upgrade" یا هر دستوری که برای به‌روزرسانی بسته‌های نصب‌شده در الگو به آخرین نسخه لازم باشد.

همچنین ببینید: --install، --uninstall.

بارگذاری فایل محلی "FILE" به مقصد "DEST" در ایمیج دیسک. مالک و مجوزهای فایل اصلی حفظ می‌شوند، بنابراین باید آن‌ها را طوری تنظیم کنید که می‌خواهید در ایمیج دیسک باشند.

مقدار "DEST" می‌تواند نام نهایی فایل باشد. این قابلیت می‌تواند برای تغییر نام فایل هنگام بارگذاری استفاده شود.

اگر "DEST" نام یک دایرکتوری باشد (که باید از قبل در مهمان وجود داشته باشد)، فایل در آن دایرکتوری بارگذاری می‌شود و نام آن در سیستم فایل محلی حفظ می‌گردد.

همچنین ببینید: --mkdir، --delete، --scrub.

نوشتن "CONTENT" در فایل "FILE".

گزینه‌های --firstboot و --firstboot-command به شما امکان می‌دهند دستوراتی را در نخستین بوت مهمان اجرا کنید. برای این منظور، یک اسکریپت init برای سیستم init مهمان نصب می‌شود که وظیفه اجرای تمامی اسکریپت‌ها و دستورات اضافه‌شده را بر عهده می‌گیرد.

در لینوکس، خروجی اسکریپت‌ها در فایل ~root/virt-sysprep-firstboot.log درون مهمان نوشته می‌شود.

در ویندوز، خروجی در فایل C:\Program Files\Guestfs\Firstboot\log.txt درون مهمان نوشته می‌شود.

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

  • 249

    فایل بچ به عنوان ناموفق تلقی می‌شود. فایل بچ در راه‌اندازی مجدد بعدی مجدداً اجرا خواهد شد. (مواظب باشید که فایل‌های بچ به طور مداوم این کد خروج را بازنگردانند، در غیر این صورت ویندوز وارد چرخه بی‌پایان بوت خواهد شد.)

  • 250

    اسکریپت نشان می‌دهد که در این مرحله نیازی به راه‌اندازی مجدد سیستم نیست. اسکریپت بعدی در توالی بدون آغاز راه‌اندازی مجدد اجرا خواهد شد.

  • هر کد دیگر

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

تنها در مهمان‌های ویندوزی، پس از پایان اجرای تمامی اسکریپت‌های بوت اولیه، یک فایل دیده‌بان (sentinel file) درون مهمان نوشته می‌شود. می‌توانید از این فایل برای تشخیص آماده بودن مهمان ویندوزی (مثلاً اتمام تبدیل توسط virt-v2v(1)) استفاده کنید. مکان پیش‌فرض این فایل به صورت زیر است:

C:\Program Files\Guestfs\Firstboot\complete

در مهمان‌های ویندوزی، ابزار rhsrvany.exe که سورس آن در https://github.com/rwmjones/rhsrvany موجود است، یا pvvxsvc.exe که با SUSE VMDP ارائه می‌شود، برای اجرای اسکریپت‌های بوت اولیه نصب می‌گردد. وجود یکی از این موارد الزامی است و در صورت عدم وجود، راه‌اندازی اسکریپت‌های بوت اولیه با شکست مواجه خواهد شد.

ابزار rhsrvany.exe یا pvvxsvc.exe از مکانی کپی می‌شود که متغیر محیطی "VIRT_TOOLS_DATA_DIR" به آن اشاره می‌کند؛ در صورت عدم تنظیم، از مقدار پیش‌فرض کامپایل‌شده (چیزی شبیه /usr/share/virt-tools) استفاده خواهد شد.

هر دو گزینه --firstboot و --script اسکریپت‌های شلی ارائه می‌دهند که بر روی مهمان اجرا می‌شوند. با این حال، این دو گزینه تفاوت‌های بنیادینی با یکدیگر دارند.

گزینه --firstboot script فایل "script" را درون مهمان بارگذاری کرده و شرایط را طوری فراهم می‌کند که هنگام بوت بعدی مهمان، در داخل خود مهمان اجرا شود.

گزینه --script اسکریپت شل را روی میزبان اجرا می‌کند، در حالی که دایرکتوری جاری آن درون سیستم فایل مهمان قرار دارد.

برای مثال، اگر نیاز دارید بسته‌های جدیدی را با "yum install" نصب کنید، نباید از --script برای این کار استفاده نمایید، چرا که این کار (الف) دستور "yum" را روی میزبان اجرا می‌کند و (ب) به منابع یکسان (مخازن، کلیدها و غیره) مشابه مهمان دسترسی نخواهد داشت. هر دستوری که باید روی مهمان اجرا شود باید از طریق --firstboot اجرا گردد.

از سوی دیگر، اگر نیاز به اعمال تغییرات روی سیستم فایل مهمان دارید (مثلاً کپی کردن فایل‌ها به داخل آن)، گزینه --script ایده‌آل است زیرا (الف) به سیستم فایل میزبان دسترسی دارد و (ب) در صورت بروز خطا بلافاصله بازخورد دریافت می‌کنید.

هر کدام از این گزینه‌ها یا هر دوی آن‌ها را می‌توان چندین بار در خط فرمان به کار برد.

برای مهمان‌هایی که از SELinux استفاده می‌کنند، هنگام استفاده از عملیاتی که فایل‌های جدیدی ایجاد کرده یا فایل‌های موجود را تغییر می‌دهند ممکن است به رفتار ویژه‌ای نیاز باشد.

برای جزئیات بیشتر، بخش "SELINUX" را در virt-builder(1) ببینید.

در نسخه 1.56 گزینه‌های subscription-manager حذف شدند: --sm-credentials، --sm-register، --sm-unregister، --sm-attach، --sm-remove

برای جزئیات بیشتر، بخش "DEPRECATED OPTIONS" را در virt-builder(1) ببینید.

این برنامه در صورت موفقیت 0 و در صورت بروز خطا 1 را برمی‌گرداند.

"VIRT_TOOLS_DATA_DIR"
این متغیر می‌تواند به دایرکتوری حاوی فایل‌های داده مورد استفاده برای نصب بوت اولیه ویندوز اشاره کند.

به طور معمول نیازی به تنظیم آن ندارید. در صورت عدم تنظیم، از یک مقدار پیش‌فرض کامپایل‌شده (چیزی مانند /usr/share/virt-tools) استفاده خواهد شد.

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

این فایل باینری ویندوزی RHSrvAny است که برای نصب یک اسکریپت "firstboot" در مهمان‌های ویندوزی استفاده می‌شود. اگر قصد دارید از گزینه‌های --firstboot یا --firstboot-command در مهمان‌های ویندوزی استفاده کنید، وجود آن الزامی است.

همچنین ببینید: "https://github.com/rwmjones/rhsrvany"

این یک فایل باینری ویندوزی است که همراه با SUSE VMDP ارائه می‌شود و برای نصب اسکریپت "firstboot" در مهمان‌های ویندوزی کاربرد دارد. اگر قصد دارید از گزینه‌های --firstboot یا --firstboot-command در مهمان‌های ویندوزی استفاده کنید، وجود آن الزامی است.

برای مشاهده سایر متغیرهای محیطی، بخش "ENVIRONMENT VARIABLES" را در guestfs(3) ببینید.

guestfs(3), guestfish(1), virt-builder(1), virt-clone(1), virt-rescue(1), virt-resize(1), virt-sparsify(1), virt-sysprep(1), virsh(1), lvcreate(8), qemu-img(1), scrub(1), http://libguestfs.org, http://libvirt.org.

Richard W.M. Jones http://people.redhat.com/~rjones

Copyright (C) 2011-2025 Red Hat Inc.

این برنامه نرم‌افزار آزاد است؛ شما می‌توانید آن را تحت شرایط «مجوز عمومی همگانی گنو» (GNU General Public License) همان‌طور که توسط بنیاد نرم‌افزارهای آزاد منتشر شده است، مجدداً توزیع نموده و/یا تغییر دهید؛ نسخه 2 مجوز یا (به انتخاب خودتان) هر نسخه بعدی.

این برنامه به این امید توزیع شده است که مفید واقع شود، اما بدون هرگونه ضمانت؛ حتی بدون ضمانت ضمنی قابلیت فروش یا مناسب بودن برای یک هدف خاص. برای جزئیات بیشتر «مجوز عمومی همگانی گنو» را مطالعه کنید.

شما باید به همراه این برنامه یک نسخه از مجوز عمومی همگانی گنو را دریافت کرده باشید؛ در غیر این صورت، به آدرس زیر نامه بنویسید: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

برای مشاهده فهرستی از اشکالات ثبت‌شده برای libguestfs، از این پیوند استفاده کنید: https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools

برای گزارش یک اشکال جدید برای libguestfs، از این پیوند استفاده کنید: https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools

هنگام گزارش اشکال، لطفاً اطلاعات زیر را ارائه دهید:

  • نسخه libguestfs.
  • محل تهیه libguestfs (مثلاً کدام توزیع لینوکس، کامپایل از سورس و غیره).
  • اشکال را با دقت توصیف نموده و روشی برای بازتولید آن ارائه دهید.
  • دستور libguestfs-test-tool(1) را اجرا کرده و خروجی کامل و دست‌نخورده آن را درون گزارش اشکال قرار دهید.
2026-07-11 guestfs-tools-1.56.0