virt-xml(1) Virtualization Support virt-xml(1)

virt-xml - ویرایش و مدیریت آسان تنظیمات XML ماشین‌های مجازی libvirt

virt-xml DOMAIN XML-ACTION XML-OPTION [OUTPUT-OPTION] [MISC-OPTIONS] ...

دستور virt-xml یک ابزار خط فرمان برای ویرایش XML در libvirt با استفاده از گزینه‌های صریح خط فرمان است. برای شروع سریع، بخش «مثال‌ها (EXAMPLES)» را در انتهای این سند ببینید.

هر بار اجرای virt-xml به ۳ چیز نیاز دارد: نام دامنه (ماشین مجازی) موجود برای تغییر (یا XML ارائه‌شده از طریق stdin)، یک عملیات بر روی XML، و تغییری که باید روی XML اعمال شود. عملیات‌ها یکی از موارد زیر هستند:

  • --add-device: افزودن تعریف یک دستگاه جدید به XML
  • --remove-device: حذف تعریف یک دستگاه موجود
  • --edit: ویرایش یک بلوک XML موجود
  • --build-xml: صرفاً ساختن بلوک XML درخواستی و چاپ آن. در اینجا نیازی به دامنه یا ورودی نیست، اما ارائه آن‌ها توصیه می‌شود تا virt-xml بتواند پیش‌فرض‌های بهینه را اعمال کند.

تغییر XML یک نمونه از هر یک از گزینه‌های XML ارائه‌شده توسط virt-xml است، مانند --disk یا --boot.

ابزار virt-xml در هر بار اجرا فقط اجازه یک جفت «عملیات و گزینه XML» را می‌دهد. اگر نیاز به اعمال چند ویرایش دارید، دستور را چند بار اجرا کنید.

اتصال به یک هایپروایزر غیرپیش‌فرض. برای جزئیات به virt-install(1) مراجعه کنید.
شناسه domain نام، UUID یا شناسه (ID) ماشین مجازی موجود است. در صورت استفاده از --build-xml یا ارسال XML از طریق ورودی استاندارد (stdin)، می‌توان این مورد را حذف کرد.

هنگامی که دامنه مشخص شده باشد، عملیات خروجی پیش‌فرض --define است، حتی اگر ماشین مجازی در حال اجرا باشد. برای به‌روزرسانی پیکربندی ماشین مجازی در حال اجرا، گزینه --update را اضافه کنید (البته همه گزینه‌ها/دستگاه‌ها از به‌روزرسانی پیکربندی ماشین مجازی در حال اجرا پشتیبانی نمی‌کنند).

اگر XML از طریق ورودی استاندارد (stdin) ارسال شود، خروجی پیش‌فرض --print-xml خواهد بود.

ویرایش بلوک XML مشخص‌شده. مقادیر EDIT-OPTIONS به virt-xml می‌گویند کدام بلوک را ویرایش کند. نوع XML مورد ویرایش بر اساس گزینه XML ارسال‌شده به virt-xml تعیین می‌شود. بنابراین اگر --disk ارسال شود، EDIT-OPTIONS مشخص می‌کند که کدام بلوک <disk> ویرایش گردد.

برخی گزینه‌های XML همیشه فقط به یک بلوک XML واحد نگاشت می‌شوند، مانند --cpu، --security، --boot، --clock و چند مورد دیگر. در این موارد، اگر بلوک XML مربوطه از قبل وجود نداشته باشد، virt-xml خطایی نمی‌گیرد و آن را برای شما ایجاد می‌کند.

بیشتر گزینه‌های XML از مقدار ویژه 'clearxml=yes' پشتیبانی می‌کنند. هنگامی که با --edit ترکیب شود، پیش از اعمال تغییرات درخواستی، بلوک XML مورد ویرایش را کاملاً خالی می‌کند. این ویژگی امکان بازسازی کامل یک بلوک XML را فراهم می‌سازد. برای نمونه‌های استفاده به بخش مثال‌ها مراجعه کنید.

نمونه‌های EDIT-OPTIONS:

•
استفاده از --edit بدون هیچ گزینه‌ای به معنای «ویرایش اولین بلوک» است. بنابراین '--edit --disk DISK-OPTIONS' به معنای «ویرایش اولین <disk>» است.

برای گزینه‌های تک‌بلوکی XML که در بالا ذکر شدند، حالت ساده '--edit' بدون هیچ گزینه‌ای دقیقاً همان چیزی است که همیشه می‌خواهید استفاده کنید.

•
انتخاب شماره بلوک XML مشخص‌شده. بنابراین '--edit 2 --disk DISK-OPTS' به معنای «ویرایش دومین <disk>» است. این گزینه عملاً فقط برای XML دستگاه‌ها کاربرد دارد.
•
اصلاح تمام بلوک‌های XML از نوع گزینه XML مشخص‌شده. بنابراین '--edit all --disk DISK-OPTS' به معنای «ویرایش تمام بلوک‌های <disk>» است. این گزینه عملاً فقط برای XML دستگاه‌ها کاربرد دارد.
•
اصلاح تمام بلوک‌های XML که با گزینه‌های دستگاه ارائه‌شده مطابقت دارند. گزینه‌های دستگاه با همان قالبی هستند که به گزینه XML ارسال می‌شوند.

بنابراین --edit path=/tmp/foo --disk DISK-OPTS به معنای «ویرایش هر <disk> با مسیر /tmp/foo» است. این گزینه عملاً فقط برای XML دستگاه‌ها کاربرد دارد.

افزودن گزینه‌های XML مشخص‌شده به فهرست <devices> در XML. مثال: '--add-device --disk DISK-OPTIONS' یک بلوک <disk> جدید ایجاد کرده و آن را به XML اضافه می‌کند.

در صورت تعیین این گزینه همراه با یک گزینه XML غیردستگاهی، خطا صادر می‌شود (برای فهرست ناقص به بخش --edit مراجعه کنید).

حذف دستگاه مشخص‌شده از XML. دستگاه مورد حذف بر اساس گزینه XML تعیین می‌شود که آرگومان‌هایی با همان قالب --edit می‌پذیرد. مثال‌ها:
•
حذف دومین دستگاه دیسک
•
حذف تمام دستگاه‌های شبکه
•
حذف تمام دستگاه‌های صوتی با مدل model='pcspk'

در صورت تعیین این گزینه همراه با یک گزینه XML غیردستگاهی، خطا صادر می‌شود (برای فهرست ناقص به بخش --edit مراجعه کنید).

صرفاً ساخت XML مشخص‌شده و چاپ آن در خروجی استاندارد (stdout). هیچ دامنه یا XML ورودی لازم نیست. مثال: '--build-xml --disk DISK-OPTIONS' صرفاً دستگاه <disk> جدید را چاپ می‌کند.

با این حال، اگر XML تولیدشده برای دامنه خاصی در نظر گرفته شده باشد، توصیه می‌شود آن را به virt-xml ارسال کنید تا این ابزار بتواند پیش‌فرض‌های بهینه را تنظیم کند.

در صورت تعیین این گزینه همراه با یک گزینه XML که به وضوح به یک بلوک مشخص XML نگاشت نمی‌شود (مانند --vcpus یا --memory)، خطا صادر می‌شود.

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

اگر دامنه مشخص‌شده در حال اجرا باشد، تلاش می‌کند پیکربندی ماشین مجازی در حال اجرا را تغییر دهد. اگر با --edit ترکیب شود، یک عملیات به‌روزرسانی خواهد بود. اگر با --add-device ترکیب شود، یک اتصال گرم (hotplug) دستگاه خواهد بود. اگر با --remove-device ترکیب شود، یک جداسازی گرم (hotunplug) دستگاه خواهد بود.

به خاطر داشته باشید که بیشتر ویژگی‌ها و دستگاه‌های XML از عملیات به‌روزرسانی زنده پشتیبانی نمی‌کنند، بنابراین انتظار نداشته باشید در همه موارد موفقیت‌آمیز باشد.

به‌طور پیش‌فرض، این گزینه --define را نیز در بر دارد.

ثبت و تعریف تغییرات XML درخواستی. این مورد معمولاً در صورت مشخص نشدن گزینه خروجی حالت پیش‌فرض است، اما اگر یکی از گزینه‌های --print مشخص شده باشد، برای اعمال اجباری تغییرات به --define نیاز است.
صریحاً XML را ثبت و تعریف نمی‌کند. برای مثال اگر فقط می‌خواهید وضعیت زمان اجرای یک ماشین مجازی را تغییر دهید، این گزینه را با --update ترکیب کنید.
روشن کردن ماشین مجازی پس از اعمال تغییرات درخواستی. اگر با --no-define ترکیب شود، یک بوت موقت ماشین مجازی با تغییرات درخواستی ایجاد خواهد کرد.
چاپ تغییرات XML تولیدشده در قالب unified diff. اگر فقط این گزینه خروجی مشخص شود، تمام گزینه‌های خروجی دیگر غیرفعال شده و هیچ تغییر پایداری اعمال نمی‌شود.
چاپ کامل XML تولیدشده. اگر فقط این گزینه خروجی مشخص شود، تمام گزینه‌های خروجی دیگر غیرفعال شده و هیچ تغییر پایداری اعمال نمی‌شود.
پیش از تعریف یا به‌روزرسانی دامنه، تفاوت (diff) تولیدشده XML را نمایش داده و به‌صورت تعاملی تاییدیه درخواست می‌کند.

بهینه‌سازی پیکربندی مهمان برای یک سیستم‌عامل خاص (مانند 'fedora29'، 'rhel7'، 'win10'). اگرچه اجباری نیست، اما تعیین این گزینه شدیداً توصیه می‌شود، زیرا می‌تواند با مشخص کردن virtio در میان سایر بهینه‌سازی‌های مهمان، عملکرد را به میزان قابل توجهی افزایش دهد.

اگر سیستم‌عامل مهمان با استفاده از virt-manager نسخه 2.0.0 یا جدیدتر نصب شده باشد، ارائه این اطلاعات نباید ضروری باشد، زیرا نوع سیستم‌عامل در طول نصب در پیکربندی مهمان ذخیره شده و virt-xml آن را به‌طور خودکار از آنجا بازیابی خواهد کرد.

از دستور virt-xml --osinfo list برای دریافت فهرست گونه‌های پذیرفته‌شده سیستم‌عامل استفاده کنید. برای خروجی‌های بیشتر دستور osinfo-query os را ببینید.

برای جزئیات بیشتر درباره --osinfo/--os-variant به مستندات virt-install(1) مراجعه کنید.

قالب دستوری: --convert-to-q35 [OPTIONS]

تبدیل پیکربندی یک ماشین مجازی موجود از نوع ماشین PC/i440FX به Q35. این کار عمدتاً شامل موارد زیر است:

  • تبدیل توپولوژی دستگاه‌ها از PCI به PCIe
  • تبدیل تمام فضاهای ذخیره‌سازی IDE به SATA

ممکن است برای مدیریت این مورد نیاز باشد تغییراتی در پیکربندی داخل ماشین مجازی نیز ایجاد کنید. برای مثال، Windows 10 ممکن است پس از تبدیل IDE به SATA نتواند دستگاه بوت را پیدا کند. اما یک‌بار بوت شدن در حالت safe mode ممکن است مشکل را برطرف کند.

زیرگزینه‌ها عبارتند از:

کنترل تعداد دستگاه‌های کنترلر پیش‌فرض pcie-root-port که به‌صورت پیش‌فرض به ماشین مجازی اضافه می‌کنیم.

قالب دستوری: --convert-to-vnc [OPTIONS]

تبدیل یک ماشین مجازی موجود برای استفاده انحصاری از یک دستگاه گرافیکی VNC واحد.

این گزینه تلاش می‌کند تمام ارجاعات به هرگونه پیکربندی گرافیکی غیر VNC مانند Spice را حذف کند. برای مثال:

  • دستگاه‌های qxl جایگزین خواهند شد
  • تمام دستگاه‌های spicevmc و spiceport حذف خواهند شد
  • گرافیک spice GL به egl-headless تبدیل خواهد شد

زیرگزینه‌ها عبارتند از:

افزودن یک دستگاه qemu-vdagent در صورتی که از قبل پیکربندی نشده باشد. این کار برخی از قابلیت‌های spice vdagent را جایگزین می‌کند. مقدار پیش‌فرض off است، اما ممکن است در آینده تغییر کند.

  • --disk
  • --network
  • --graphics
  • --metadata
  • --memory
  • --vcpus
  • --cpu
  • --iothreads
  • --seclabel
  • --keywrap
  • --cputune
  • --numatune
  • --memtune
  • --blkiotune
  • --memorybacking
  • --features
  • --clock
  • --pm
  • --events
  • --resources
  • --sysinfo
  • --xml
  • --qemu-commandline
  • --launchSecurity
  • --boot
  • --idmap
  • --controller
  • --input
  • --serial
  • --parallel
  • --channel
  • --console
  • --hostdev
  • --filesystem
  • --sound
  • --audio
  • --watchdog
  • --video
  • --smartcard
  • --redirdev
  • --memballoon
  • --tpm
  • --rng
  • --panic
  • --shmem
  • --memdev

این گزینه‌ها XML را برای یک دسته واحد از عناصر XML تغییر می‌دهند. مستندات کامل‌تر در virt-install(1) یافت می‌شود.

به‌طور کلی این گزینه‌ها کاملاً سرراست به XML هایپروایزر libvirt نگاشت می‌شوند که در نشانی https://libvirt.org/formatdomain.html مستند شده است.

رشته‌های گزینه در قالب زیر هستند: --option opt=val,opt2=val2,... به عنوان مثال: --disk path=/tmp/foo,shareable=on. ویژگی‌ها را می‌توان به‌صورت '--option opt=,' نیز استفاده کرد، بنابراین برای پاک کردن تنظیمات cache یک دیسک می‌توانید از '--disk cache=,' استفاده کنید.

برای هر گزینه، از --option=? برای دیدن فهرستی از تمام زیرگزینه‌های موجود استفاده کنید، به عنوان مثال: --disk=? یا --boot=?

خروجی --help نیز چند مثال عمومی را فهرست می‌کند. برای مشاهده مثال‌های متداول به بخش «مثال‌ها (EXAMPLES)» در زیر مراجعه کنید.

ابزار virt-xml به‌طور خاص دارای برخی عملیات است که واقعاً برای virt-install کاربرد ندارند. مثال‌ها:

بازنشانی مقدار <os><type machine=X></os> در XML به آخرین مقداری که qemu ارائه می‌دهد. به عنوان مثال، اگر ماشین مجازی شما مقدار نوع ماشین pc-q35-4.0 را دارد، این گزینه مقدار را به q35 بازنشانی می‌کند، و به همین ترتیب با سایر انواع ماشین‌های دارای نسخه نیز کار می‌کند. گاهی این کار برای فعال‌سازی رفع اشکال‌های qemu، یا زمانی که qemu مقادیر قدیمی نوع ماشین را منسوخ و حذف می‌کند، ضروری است.

نمایش پیام راهنما و خروج
نمایش شماره نسخه برنامه و خروج
جلوگیری از خروجی‌های پرحجم
چاپ اطلاعات اشکال‌زدایی (دیباگ)

مشاهده فهرستی از تمام زیرگزینه‌هایی که --disk و --network می‌پذیرند:

# virt-xml --disk=? --network=?

تغییر <description> دامنه 'EXAMPLE':

# virt-xml EXAMPLE --edit --metadata description="my new description"

فعال کردن منوی دستگاه بوت برای دامنه 'EXAMPLE':

# virt-xml EXAMPLE --edit --boot menu=on

پاک کردن تعریف قبلی <cpu> دامنه 'winxp'، تغییر آن به 'host-model'، همراه با تایید تعاملی diff پیش از ذخیره:

# virt-xml winxp --edit --cpu host-model,clearxml=yes --confirm

تغییر دومین کارت صدا به model=ich6 در 'fedora19'، اما فقط چاپ تفاوت‌ها (diff):

# virt-xml fedora19 --edit 2 --sound model=ich6 --print-diff

به‌روزرسانی گذرواژه تمام دستگاه‌های گرافیکی به 'foo' در ماشین مجازی در حال اجرای 'rhel6':

# virt-xml rhel6 --edit all --graphics password=foo --update

حذف مسیر دیسک از دستگاه دیسک hdc:

# virt-xml rhel6 --edit target=hdc --disk path=

تغییر تمام دستگاه‌های دیسک از نوع 'disk' به cache=none، با استفاده از XML ورودی stdin، و چاپ XML جدید در stdout:

# cat <xmlfile> | virt-xml --edit device=disk --disk cache=none

تغییر ورودی/خروجی (IO) دیسک 'hda' به native و استفاده از سیاست راه‌اندازی 'optional':

# virt-xml fedora20 --edit target=hda \
           --disk io=native,startup_policy=optional

تغییر تمام دستگاه‌های میزبان به driver_name=vfio برای ماشین مجازی 'fedora20' در اتصال از راه دور:

# virt-xml --connect qemu+ssh://remotehost/system \
           fedora20 --edit all --hostdev driver_name=vfio

اتصال گرم (Hotplug) دستگاه USB میزبان 001.003 به دامنه در حال اجرای 'fedora19':

# virt-xml fedora19 --update --add-device --hostdev 001.003

افزودن یک کانال spicevmc به دامنه 'winxp'، که پس از خاموش شدن بعدی ماشین مجازی در دسترس خواهد بود:

# virt-xml winxp --add-device --channel spicevmc

ایجاد یک ایمیج دیسک qcow2 به حجم 10 گیگابایت و اتصال آن به 'fedora18' برای راه‌اندازی بعدی ماشین مجازی:

# virt-xml fedora18 --add-device \
  --disk /var/lib/libvirt/images/newimage.qcow2,format=qcow2,size=10

مشابه بالا، اما با اطمینان از اتصال دیسک به مناسب‌ترین گذرگاه برای سیستم‌عامل مهمان با ارائه اطلاعات آن در خط فرمان:

# virt-xml fedora18 --osinfo fedora18 --add-device \
  --disk /var/lib/libvirt/images/newimage.qcow2,format=qcow2,size=10

جداسازی گرم (Hotunplug) دیسک vdb از دامنه در حال اجرای 'rhel7':

# virt-xml rhel7 --update --remove-device --disk target=vdb

حذف تمام دستگاه‌های گرافیکی از ماشین مجازی 'rhel7' پس از خاموش شدن بعدی:

# virt-xml rhel7 --remove-device --graphics all

تولید XML برای یک دستگاه کنسول virtio و چاپ آن در stdout:

# virt-xml --build-xml --console pty,target_type=virtio

افزودن دستور مستقیم پاس‌ترو در خط فرمان qemu:

# virt-xml f25 --edit --confirm --qemu-commandline="-device FOO"

استفاده از دستگاه بوت 'network' برای یک‌بار بوت موقت:

# virt-xml myvm --no-define --start --edit --boot network

میزبان‌های مجازی‌سازی پشتیبانی‌شده توسط libvirt ممکن است اجازه تمام تغییراتی که ممکن به نظر می‌رسد را ندهند. برخی ویرایش‌های انجام‌شده روی تعریف یک ماشین مجازی ممکن است نادیده گرفته شوند. به عنوان مثال، QEMU پس از تعریف برخی دستگاه‌ها، اجازه حذف آن‌ها را نمی‌دهد.

لطفاً به نشانی https://virt-manager.org/bugs مراجعه کنید.

حق نشر (C) شرکت Red Hat و مشارکت‌کنندگان مختلف. این یک نرم‌افزار آزاد است. شما می‌توانید نسخه‌های آن را تحت شرایط «مجوز عمومی همگانی گنو» https://www.gnu.org/licenses/gpl.html بازتوزیع کنید. تا جایی که قانون اجازه می‌دهد، هیچ ضمانتی وجود ندارد.

virt-install(1)، وب‌سایت پروژه https://virt-manager.org