virt-xml(1) Virtualization Support virt-xml(1) نام (NAME) virt-xml - ویرایش و مدیریت آسان تنظیمات XML ماشین‌های مجازی libvirt خلاصه دستور (SYNOPSIS) virt-xml DOMAIN XML-ACTION XML-OPTION [OUTPUT-OPTION] [MISC-OPTIONS] ... توضیحات (DESCRIPTION) دستور 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» را می‌دهد. اگر نیاز به اعمال چند ویرایش دارید، دستور را چند بار اجرا کنید. گزینه‌ها (OPTIONS) -c --connect URI اتصال به یک هایپروایزر غیرپیش‌فرض. برای جزئیات به virt-install(1) مراجعه کنید. domain شناسه domain نام، UUID یا شناسه (ID) ماشین مجازی موجود است. در صورت استفاده از --build-xml یا ارسال XML از طریق ورودی استاندارد (stdin)، می‌توان این مورد را حذف کرد. هنگامی که دامنه مشخص شده باشد، عملیات خروجی پیش‌فرض --define است، حتی اگر ماشین مجازی در حال اجرا باشد. برای به‌روزرسانی پیکربندی ماشین مجازی در حال اجرا، گزینه --update را اضافه کنید (البته همه گزینه‌ها/دستگاه‌ها از به‌روزرسانی پیکربندی ماشین مجازی در حال اجرا پشتیبانی نمی‌کنند). اگر XML از طریق ورودی استاندارد (stdin) ارسال شود، خروجی پیش‌فرض --print-xml خواهد بود. عملیات‌های XML (XML ACTIONS) --edit [EDIT-OPTIONS] ویرایش بلوک XML مشخص‌شده. مقادیر EDIT-OPTIONS به virt-xml می‌گویند کدام بلوک را ویرایش کند. نوع XML مورد ویرایش بر اساس گزینه XML ارسال‌شده به virt-xml تعیین می‌شود. بنابراین اگر --disk ارسال شود، EDIT-OPTIONS مشخص می‌کند که کدام بلوک ویرایش گردد. برخی گزینه‌های XML همیشه فقط به یک بلوک XML واحد نگاشت می‌شوند، مانند --cpu، --security، --boot، --clock و چند مورد دیگر. در این موارد، اگر بلوک XML مربوطه از قبل وجود نداشته باشد، virt-xml خطایی نمی‌گیرد و آن را برای شما ایجاد می‌کند. بیشتر گزینه‌های XML از مقدار ویژه 'clearxml=yes' پشتیبانی می‌کنند. هنگامی که با --edit ترکیب شود، پیش از اعمال تغییرات درخواستی، بلوک XML مورد ویرایش را کاملاً خالی می‌کند. این ویژگی امکان بازسازی کامل یک بلوک XML را فراهم می‌سازد. برای نمونه‌های استفاده به بخش مثال‌ها مراجعه کنید. نمونه‌های EDIT-OPTIONS: • --edit استفاده از --edit بدون هیچ گزینه‌ای به معنای «ویرایش اولین بلوک» است. بنابراین '--edit --disk DISK-OPTIONS' به معنای «ویرایش اولین » است. برای گزینه‌های تک‌بلوکی XML که در بالا ذکر شدند، حالت ساده '--edit' بدون هیچ گزینه‌ای دقیقاً همان چیزی است که همیشه می‌خواهید استفاده کنید. • --edit # انتخاب شماره بلوک XML مشخص‌شده. بنابراین '--edit 2 --disk DISK-OPTS' به معنای «ویرایش دومین » است. این گزینه عملاً فقط برای XML دستگاه‌ها کاربرد دارد. • --edit all اصلاح تمام بلوک‌های XML از نوع گزینه XML مشخص‌شده. بنابراین '--edit all --disk DISK-OPTS' به معنای «ویرایش تمام بلوک‌های » است. این گزینه عملاً فقط برای XML دستگاه‌ها کاربرد دارد. • --edit DEVICE-OPTIONS اصلاح تمام بلوک‌های XML که با گزینه‌های دستگاه ارائه‌شده مطابقت دارند. گزینه‌های دستگاه با همان قالبی هستند که به گزینه XML ارسال می‌شوند. بنابراین --edit path=/tmp/foo --disk DISK-OPTS به معنای «ویرایش هر با مسیر /tmp/foo» است. این گزینه عملاً فقط برای XML دستگاه‌ها کاربرد دارد. --add-device افزودن گزینه‌های XML مشخص‌شده به فهرست در XML. مثال: '--add-device --disk DISK-OPTIONS' یک بلوک جدید ایجاد کرده و آن را به XML اضافه می‌کند. در صورت تعیین این گزینه همراه با یک گزینه XML غیردستگاهی، خطا صادر می‌شود (برای فهرست ناقص به بخش --edit مراجعه کنید). --remove-device حذف دستگاه مشخص‌شده از XML. دستگاه مورد حذف بر اساس گزینه XML تعیین می‌شود که آرگومان‌هایی با همان قالب --edit می‌پذیرد. مثال‌ها: • --remove-device --disk 2 حذف دومین دستگاه دیسک • --remove-device --network all حذف تمام دستگاه‌های شبکه • --remove-device --sound pcspk حذف تمام دستگاه‌های صوتی با مدل model='pcspk' در صورت تعیین این گزینه همراه با یک گزینه XML غیردستگاهی، خطا صادر می‌شود (برای فهرست ناقص به بخش --edit مراجعه کنید). --build-xml صرفاً ساخت XML مشخص‌شده و چاپ آن در خروجی استاندارد (stdout). هیچ دامنه یا XML ورودی لازم نیست. مثال: '--build-xml --disk DISK-OPTIONS' صرفاً دستگاه جدید را چاپ می‌کند. با این حال، اگر XML تولیدشده برای دامنه خاصی در نظر گرفته شده باشد، توصیه می‌شود آن را به virt-xml ارسال کنید تا این ابزار بتواند پیش‌فرض‌های بهینه را تنظیم کند. در صورت تعیین این گزینه همراه با یک گزینه XML که به وضوح به یک بلوک مشخص XML نگاشت نمی‌شود (مانند --vcpus یا --memory)، خطا صادر می‌شود. گزینه‌های خروجی (OUTPUT OPTIONS) این گزینه‌ها تعیین می‌کنند که پس از تغییر XML چه عملیاتی انجام شود. در حالت معمول نیازی به مشخص کردن این گزینه‌ها نیست، زیرا «عملیات‌های XML» یک عملیات خروجی پیش‌فرض را در بر دارند که در بالا با جزئیات توضیح داده شد. این گزینه‌ها فقط زمانی لازم هستند که بخواهید خروجی پیش‌فرض را تغییر دهید. --update اگر دامنه مشخص‌شده در حال اجرا باشد، تلاش می‌کند پیکربندی ماشین مجازی در حال اجرا را تغییر دهد. اگر با --edit ترکیب شود، یک عملیات به‌روزرسانی خواهد بود. اگر با --add-device ترکیب شود، یک اتصال گرم (hotplug) دستگاه خواهد بود. اگر با --remove-device ترکیب شود، یک جداسازی گرم (hotunplug) دستگاه خواهد بود. به خاطر داشته باشید که بیشتر ویژگی‌ها و دستگاه‌های XML از عملیات به‌روزرسانی زنده پشتیبانی نمی‌کنند، بنابراین انتظار نداشته باشید در همه موارد موفقیت‌آمیز باشد. به‌طور پیش‌فرض، این گزینه --define را نیز در بر دارد. --define ثبت و تعریف تغییرات XML درخواستی. این مورد معمولاً در صورت مشخص نشدن گزینه خروجی حالت پیش‌فرض است، اما اگر یکی از گزینه‌های --print مشخص شده باشد، برای اعمال اجباری تغییرات به --define نیاز است. --no-define صریحاً XML را ثبت و تعریف نمی‌کند. برای مثال اگر فقط می‌خواهید وضعیت زمان اجرای یک ماشین مجازی را تغییر دهید، این گزینه را با --update ترکیب کنید. --start روشن کردن ماشین مجازی پس از اعمال تغییرات درخواستی. اگر با --no-define ترکیب شود، یک بوت موقت ماشین مجازی با تغییرات درخواستی ایجاد خواهد کرد. --print-diff چاپ تغییرات XML تولیدشده در قالب unified diff. اگر فقط این گزینه خروجی مشخص شود، تمام گزینه‌های خروجی دیگر غیرفعال شده و هیچ تغییر پایداری اعمال نمی‌شود. --print-xml چاپ کامل XML تولیدشده. اگر فقط این گزینه خروجی مشخص شود، تمام گزینه‌های خروجی دیگر غیرفعال شده و هیچ تغییر پایداری اعمال نمی‌شود. --confirm پیش از تعریف یا به‌روزرسانی دامنه، تفاوت (diff) تولیدشده XML را نمایش داده و به‌صورت تعاملی تاییدیه درخواست می‌کند. گزینه‌های سیستم‌عامل مهمان (GUEST OS OPTIONS) --osinfo, --os-variant OS_VARIANT بهینه‌سازی پیکربندی مهمان برای یک سیستم‌عامل خاص (مانند 'fedora29'، 'rhel7'، 'win10'). اگرچه اجباری نیست، اما تعیین این گزینه شدیداً توصیه می‌شود، زیرا می‌تواند با مشخص کردن virtio در میان سایر بهینه‌سازی‌های مهمان، عملکرد را به میزان قابل توجهی افزایش دهد. اگر سیستم‌عامل مهمان با استفاده از virt-manager نسخه 2.0.0 یا جدیدتر نصب شده باشد، ارائه این اطلاعات نباید ضروری باشد، زیرا نوع سیستم‌عامل در طول نصب در پیکربندی مهمان ذخیره شده و virt-xml آن را به‌طور خودکار از آنجا بازیابی خواهد کرد. از دستور virt-xml --osinfo list برای دریافت فهرست گونه‌های پذیرفته‌شده سیستم‌عامل استفاده کنید. برای خروجی‌های بیشتر دستور osinfo-query os را ببینید. برای جزئیات بیشتر درباره --osinfo/--os-variant به مستندات virt-install(1) مراجعه کنید. گزینه‌های تبدیل (CONVERSION OPTIONS) --convert-to-q35 قالب دستوری: --convert-to-q35 [OPTIONS] تبدیل پیکربندی یک ماشین مجازی موجود از نوع ماشین PC/i440FX به Q35. این کار عمدتاً شامل موارد زیر است: • تبدیل توپولوژی دستگاه‌ها از PCI به PCIe • تبدیل تمام فضاهای ذخیره‌سازی IDE به SATA ممکن است برای مدیریت این مورد نیاز باشد تغییراتی در پیکربندی داخل ماشین مجازی نیز ایجاد کنید. برای مثال، Windows 10 ممکن است پس از تبدیل IDE به SATA نتواند دستگاه بوت را پیدا کند. اما یک‌بار بوت شدن در حالت safe mode ممکن است مشکل را برطرف کند. زیرگزینه‌ها عبارتند از: num_pcie_root_ports=NUM کنترل تعداد دستگاه‌های کنترلر پیش‌فرض pcie-root-port که به‌صورت پیش‌فرض به ماشین مجازی اضافه می‌کنیم. --convert-to-vnc قالب دستوری: --convert-to-vnc [OPTIONS] تبدیل یک ماشین مجازی موجود برای استفاده انحصاری از یک دستگاه گرافیکی VNC واحد. این گزینه تلاش می‌کند تمام ارجاعات به هرگونه پیکربندی گرافیکی غیر VNC مانند Spice را حذف کند. برای مثال: • دستگاه‌های qxl جایگزین خواهند شد • تمام دستگاه‌های spicevmc و spiceport حذف خواهند شد • گرافیک spice GL به egl-headless تبدیل خواهد شد زیرگزینه‌ها عبارتند از: qemu-vdagent=on|off افزودن یک دستگاه qemu-vdagent در صورتی که از قبل پیکربندی نشده باشد. این کار برخی از قابلیت‌های spice vdagent را جایگزین می‌کند. مقدار پیش‌فرض off است، اما ممکن است در آینده تغییر کند. گزینه‌های XML (XML OPTIONS) • --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 نگاشت می‌شوند که در نشانی مستند شده است. رشته‌های گزینه در قالب زیر هستند: --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 کاربرد ندارند. مثال‌ها: --boot refresh-machine-type=yes بازنشانی مقدار در XML به آخرین مقداری که qemu ارائه می‌دهد. به عنوان مثال، اگر ماشین مجازی شما مقدار نوع ماشین pc-q35-4.0 را دارد، این گزینه مقدار را به q35 بازنشانی می‌کند، و به همین ترتیب با سایر انواع ماشین‌های دارای نسخه نیز کار می‌کند. گاهی این کار برای فعال‌سازی رفع اشکال‌های qemu، یا زمانی که qemu مقادیر قدیمی نوع ماشین را منسوخ و حذف می‌کند، ضروری است. گزینه‌های متفرقه (MISCELLANEOUS OPTIONS) -h, --help نمایش پیام راهنما و خروج --version نمایش شماره نسخه برنامه و خروج -q, --quiet جلوگیری از خروجی‌های پرحجم -d, --debug چاپ اطلاعات اشکال‌زدایی (دیباگ) مثال‌ها (EXAMPLES) مشاهده فهرستی از تمام زیرگزینه‌هایی که --disk و --network می‌پذیرند: # virt-xml --disk=? --network=? تغییر دامنه 'EXAMPLE': # virt-xml EXAMPLE --edit --metadata description="my new description" فعال کردن منوی دستگاه بوت برای دامنه 'EXAMPLE': # virt-xml EXAMPLE --edit --boot menu=on پاک کردن تعریف قبلی دامنه '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 | 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 هشدارها (CAVEATS) میزبان‌های مجازی‌سازی پشتیبانی‌شده توسط libvirt ممکن است اجازه تمام تغییراتی که ممکن به نظر می‌رسد را ندهند. برخی ویرایش‌های انجام‌شده روی تعریف یک ماشین مجازی ممکن است نادیده گرفته شوند. به عنوان مثال، QEMU پس از تعریف برخی دستگاه‌ها، اجازه حذف آن‌ها را نمی‌دهد. اشکالات (BUGS) لطفاً به نشانی مراجعه کنید. حق نشر (COPYRIGHT) حق نشر (C) شرکت Red Hat و مشارکت‌کنندگان مختلف. این یک نرم‌افزار آزاد است. شما می‌توانید نسخه‌های آن را تحت شرایط «مجوز عمومی همگانی گنو» بازتوزیع کنید. تا جایی که قانون اجازه می‌دهد، هیچ ضمانتی وجود ندارد. همچنین ببینید (SEE ALSO) virt-install(1)، وب‌سایت پروژه virt-xml(1)