help

شکل دستوری:

help [command-or-group]

این دستور تک‌تک دستورهای virsh را فهرست می‌کند. هنگامی که بدون گزینه استفاده شود، تمام دستورها در گروه‌های مرتبط و هر کدام در یک خط فهرست شده و کلیدواژهٔ مربوط به هر گروه نمایش داده می‌شود.

برای نمایش فقط دستورهای مربوط به یک گروه خاص، کلیدواژهٔ آن گروه را به عنوان گزینه وارد کنید. برای نمونه:

مثال ۱:

virsh # help host
Host and Hypervisor (help keyword 'host'):
    capabilities                   capabilities
    cpu-models                     show the CPU models for an architecture
    connect                        (re)connect to hypervisor
    freecell                       NUMA free memory
    hostname                       print the hypervisor hostname
    qemu-attach                    Attach to existing QEMU process
    qemu-monitor-command           QEMU Monitor Command
    qemu-agent-command             QEMU Guest Agent Command
    sysinfo                        print the hypervisor sysinfo
    uri                            print the hypervisor canonical URI

برای نمایش اطلاعات دقیق‌تر دربارهٔ یک دستور خاص، نام آن را به جای گروه به عنوان گزینه وارد کنید. برای نمونه:

مثال ۲:

virsh # help list
  NAME
    list - list domains
  SYNOPSIS
    list [--inactive] [--all]
  DESCRIPTION
    Returns list of domains.
  OPTIONS
    --inactive       list inactive domains
    --all            list inactive & active domains

quit
exit

version

نحو:

version [--daemon]

اطلاعات نسخه اصلی نرم‌افزاری که این ابزار از آن ساخته شده است را چاپ می‌کند. اگر --daemon مشخص شده باشد، نسخه دیمن libvirt نیز در خروجی گنجانده می‌شود.

مثال:

$ virsh version
Compiled against library: libvirt 1.2.3
Using library: libvirt 1.2.3
Using API: QEMU 1.2.3
Running hypervisor: QEMU 2.0.50
$ virsh version --daemon
Compiled against library: libvirt 1.2.3
Using library: libvirt 1.2.3
Using API: QEMU 1.2.3
Running hypervisor: QEMU 2.0.50
Running against daemon: 1.2.6

cd

نحو:

cd [directory]

دایرکتوری جاری را به directory تغییر می‌دهد. دایرکتوری پیش‌فرض برای دستور cd دایرکتوری خانگی است، یا در صورتی که متغیر HOME در محیط وجود نداشته باشد، دایرکتوری ریشه (root) خواهد بود.

pwd

نحو:

pwd

دایرکتوری جاری را چاپ می‌کند.

connect

نحو:

connect [URI] [--readonly]

اتصال (یا اتصال مجدد) به هایپروایزر. هنگامی که شل برای نخستین بار آغاز به کار می‌کند، این دستور به صورت خودکار با پارامتر URI که توسط گزینه -c در خط فرمان درخواست شده، اجرا می‌شود. پارامتر URI نحوه اتصال به هایپروایزر را مشخص می‌کند. مستندات مربوط به URI در https://libvirt.org/uri.html مقادیر پشتیبانی‌شده را فهرست می‌کنند، اما رایج‌ترین آن‌ها عبارتند از:

برای یافتن URI مورد استفاده فعلی، دستور uri را که در ادامه مستند شده بررسی کنید.

برای دسترسی از راه دور، مستندات URI در https://libvirt.org/uri.html را در مورد نحوه ایجاد URIها مشاهده نمایید. گزینه --readonly امکان اتصال فقط‌خواندنی را فراهم می‌کند.SS uri

نحو:

uri

نشانی URI متعارف (canonical) هایپروایزر را چاپ می‌کند؛ که می‌تواند در حالت پوسته (shell mode) مفید باشد.

hostname

نحو:

hostname

نام میزبان (hostname) هایپروایزر را چاپ می‌کند.

sysinfo

نحو:

sysinfo

نمایش XML اطلاعات سیستم (sysinfo) هایپروایزر را، در صورت در دسترس بودن، چاپ می‌کند.

nodeinfo

نحو:

nodeinfo

اطلاعات پایه‌ای دربارهٔ گره (node)، مانند تعداد و نوع پردازنده، و اندازهٔ حافظهٔ فیزیکی را بازمی‌گرداند.

استفاده از این دستور شدیداً منع می‌شود، چرا که تضمینی برای دقیق بودن اطلاعات ارائه‌شده در تمامی پلتفرم‌های سخت‌افزاری وجود ندارد.

مقدار CPU frequency صرفاً نمایانگر سرعتی است که نخستین پردازنده در ماشین در حال حاضر با آن کار می‌کند. این سرعت ممکن است در میان پردازنده‌ها متفاوت باشد و با تنظیم خودکار توان (throttle) توسط سیستم‌عامل میزبان به‌طور مداوم تغییر کند.

ساختار دادهٔ استفاده‌شده برای دریافت این اطلاعات قابل گسترش نیست، بنابراین تنها از اطلاعات توپولوژی سراسری nodes/sockets/cores/threads (که sockets/cores/threads به ازای هر گرهٔ NUMA است) پشتیبانی می‌کند. چنانچه پردازندهٔ میزبان گروه‌بندی‌های بیشتری داشته باشد (مانند dies، clusters و غیره) یا توپولوژی NUMA غیرمتقارن باشد، این ساختار داده نمی‌تواند سیستم را به‌درستی بازنمایی کند. در چنین مواردی، یک توپولوژی ساختگی (nodes = 1, sockets = 1, cores = number of host cpus, threads = 1) گزارش می‌شود که تنها تعداد کل پردازنده‌های میزبان را به‌درستی نشان می‌دهد.

جایگزین پیشنهادی، استفاده از دستور capabilities است که این اطلاعات را (به‌جز فرکانس) در مسیر /capabilities/host/topology در XPath گزارش می‌دهد.

nodecpumap

نحو:

nodecpumap [--pretty]

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

با --pretty پردازنده‌های برخط به‌جای یک فهرست، به‌صورت یک محدوده (range) چاپ می‌شوند..SS nodecpustats

نحو:

nodecpustats [cpu] [--percent]

آمار پردازنده (CPU) گره را بازمی‌گرداند. اگر cpu مشخص شده باشد، تنها آمار مربوط به پردازنده مشخص‌شده را چاپ می‌کند. اگر --percent مشخص شده باشد، درصد هر نوع از آمارهای پردازنده را در طول ۱ ثانیه چاپ می‌کند.

nodememstats

نحو:

nodememstats [cell]

آمار حافظه گره را بازمی‌گرداند. اگر cell مشخص شده باشد، تنها آمار سلول مشخص‌شده را چاپ می‌کند.

nodesevinfo

نحو:

nodesevinfo

اطلاعات مربوط به قابلیت‌های امنیتی راه‌اندازی AMD SEV را برای گره (در صورت وجود) گزارش می‌دهد. بخشی از این اطلاعات در سند XML قابلیت‌های دامنه (domain capabilities) نیز گزارش می‌شود.

nodesuspend

نحو:

nodesuspend [target] [duration]

گره (ماشین میزبان) را در وضعیت خواب سراسری سیستم قرار داده و وقفه ساعت زمان‌واقعی (Real-Time-Clock) گره را زمان‌بندی می‌کند تا پس از اتمام مدت‌زمان تعیین‌شده در duration، گره مجدداً بیدار شود. target وضعیتی را که میزبان باید به آن معلق شود تعیین می‌کند؛ این مقدار می‌تواند "mem" (تعلیق در رم)، "disk" (تعلیق روی دیسک)، یا "hybrid" (تعلیق ترکیبی روی رم و دیسک) باشد. duration مدت‌زمان تعلیق میزبان را بر حسب ثانیه مشخص می‌کند که باید حداقل ۶۰ ثانیه باشد.

node-memory-tune

نحو:

node-memory-tune [shm-pages-to-scan] [shm-sleep-millisecs] [shm-merge-across-nodes]

به شما امکان می‌دهد پارامترهای حافظه گره را نمایش داده یا تنظیم کنید. از shm-pages-to-scan می‌توان برای تنظیم تعداد صفحاتی که باید قبل از رفتن سرویس حافظه اشتراکی به حالت خواب اسکن شوند، استفاده کرد؛ از shm-sleep-millisecs می‌توان برای تعیین مدت‌زمانی (به میلی‌ثانیه) که سرویس حافظه اشتراکی باید قبل از اسکن بعدی بخوابد، بهره برد؛ shm-merge-across-nodes مشخص می‌کند که آیا ادغام صفحات از گره‌های NUMA مختلف مجاز است یا خیر. هنگامی که روی 0 تنظیم شود، تنها صفحاتی که به صورت فیزیکی در ناحیه حافظه یک گره NUMA یکسان قرار دارند می‌توانند ادغام شوند. هنگامی که روی 1 تنظیم شود، صفحات مربوط به تمام گره‌ها قابل ادغام هستند. پیش‌فرض 1 است.

نکته: در حال حاضر عبارت "سرویس حافظه اشتراکی" فقط به معنای KSM (Kernel Samepage Merging) است..SS capabilities

نحو:

capabilities [--xpath EXPRESSION] [--wrap]

یک سند XML چاپ می‌کند که قابلیت‌های هایپروایزری که در حال حاضر به آن متصل هستیم را توصیف می‌نماید. این سند شامل بخشی دربارهٔ قابلیت‌های میزبان از نظر CPU و ویژگی‌ها، و مجموعه‌ای از توضیحات برای هر نوع مهمانی است که می‌تواند مجازی‌سازی شود. برای توضیحات کامل‌تر ببینید:

https://libvirt.org/formatcaps.html

این XML همچنین اطلاعات توپولوژی NUMA را در صورت در دسترس بودن نشان می‌دهد.

اگر آرگومان --xpath یک عبارت XPath را ارائه دهد، روی خروجی XML ارزیابی شده و تنها گره‌های منطبق چاپ خواهند شد. رفتار پیش‌فرض این است که هر گره منطبق به‌صورت یک سند مستقل چاپ شود، با این حال، جهت سهولت در پردازش‌های بیشتر، آرگومان --wrap باعث می‌شود گره‌های منطبق درون یک گره ریشه مشترک قرار گیرند.

domcapabilities

نحو:

domcapabilities [virttype] [emulatorbin] [arch] [machine]
                [--xpath EXPRESSION] [--wrap]
                [--disable-deprecated-features]
                [--expand-cpu-features] [--supported-cpu-features]

یک سند XML را چاپ می‌کند که قابلیت‌های دامنه (domain) را برای هایپروایزری که به آن متصل هستیم، با استفاده از اطلاعاتی که یا از یک دامنه موجود یا از خروجی virsh capabilities گرفته شده است، توصیف می‌نماید. این دستور می‌تواند زمانی مفید باشد که قصد ایجاد یک دامنه جدید را دارید و می‌خواهید بدانید، به عنوان مثال، آیا می‌تواند با ایجاد یک دامنه برای هایپروایزر با یک شبیه‌ساز (emulator) و معماری خاص از VFIO استفاده کند یا خیر.

هر هایپروایزر نیازمندی‌های متفاوتی در رابطه با اینکه کدام گزینه‌ها الزامی و کدام اختیاری هستند خواهد داشت. یک هایپروایزر می‌تواند از ارائه مقدار پیش‌فرض برای هر یک از گزینه‌ها پشتیبانی کند.

گزینه virttype نوع مجازی‌سازی مورد استفاده را مشخص می‌کند. مقدار مورد استفاده می‌تواند از مشخصه 'type' عنصر سطح‌بالای <domain/> در XML دامنه، یا مشخصه 'type' موجود در هر عنصر <guest/> از خروجی virsh capabilities باشد. گزینه emulatorbin مسیر شبیه‌ساز را مشخص می‌کند. مقدار مورد استفاده یا عنصر <emulator> در XML دامنه است یا خروجی virsh capabilities. گزینه arch معماری مورد استفاده برای دامنه را مشخص می‌کند. مقدار مورد استفاده یا مشخصه "arch" از عنصر <os/> و زیرعنصر <type/> در XML دامنه است، یا مشخصه "name" یک عنصر <arch/> از خروجی virsh capabilities. گزینه machine نوع ماشین را برای شبیه‌ساز مشخص می‌کند. مقدار مورد استفاده یا مشخصه "machine" از عنصر <os/> و زیرعنصر <type/> در XML دامنه است، یا مقداری از فهرست ماشین‌ها از خروجی virsh capabilities برای یک معماری و نوع دامنه خاص.

برای هایپروایزر QEMU، مقدار virttype باید یکی از مقادیر 'qemu' یا 'kvm' باشد و به همراه emulatorbin یا arch ارائه شود تا خروجی برای machine پیش‌فرض تولید گردد. ارائه یک مقدار برای machine خروجی را برای آن ماشین خاص تولید خواهد کرد.

اگر آرگومان --xpath یک عبارت XPath را ارائه دهد، روی خروجی XML ارزیابی شده و تنها گره‌های منطبق چاپ خواهند شد. رفتار پیش‌فرض این است که هر گره منطبق به‌صورت یک سند مستقل چاپ شود، با این حال، جهت سهولت در پردازش‌های بیشتر، آرگومان --wrap باعث می‌شود گره‌های منطبق درون یک گره ریشه مشترک قرار گیرند.

آرگومان --disable-deprecated-features محتوای XML مربوط به CPU مدل میزبان (host-model) را اصلاح کرده و فهرست ویژگی‌ها را با هر ویژگی که توسط هایپروایزر برای مدل CPU منسوخ اعلام شده است، به‌روزرسانی می‌کند. این ویژگی‌ها با خط‌مشی "disable" جفت خواهند شد.

گزینه --expand-cpu-features باعث می‌شود تعریف CPU مدل میزبان (host-model) شامل تمام ویژگی‌های مورد نیاز CPU، از جمله مواردی که به‌طور ضمنی توسط مدل CPU انتخاب‌شده فعال شده‌اند، باشد. بدون این پرچم، ویژگی‌هایی که بخشی از خود مدل CPU هستند فهرست نخواهند شد.

گزینه --supported-cpu-features تعریف CPU مدل میزبان (host-model) را با ویژگی‌هایی به‌روزرسانی می‌کند که روی میزبان پشتیبانی می‌شوند، اما هنگام راه‌اندازی یک دامنه با CPU مدل میزبان به‌صورت پیش‌فرض فعال نخواهند شد. استفاده هم‌زمان از هر دو گزینه --supported-cpu-features و --expand-cpu-features فهرستی کامل از ویژگی‌هایی که می‌توان روی میزبان فعال کرد را ارائه می‌دهد..SS pool-capabilities

ساختار دستوری:

pool-capabilities

یک سند XML را چاپ می‌کند که قابلیت‌های مخزن ذخیره‌سازی (storage pool) را برای درایور ذخیره‌سازی متصل توصیف می‌کند. این دستور زمانی مفید است که قصد ایجاد یک مخزن ذخیره‌سازی جدید دارید و نیازمند آگاهی از انواع مخزن‌های در دسترس، قالب‌های حجم‌های مبدا و مقصد پشتیبانی‌شده و همچنین عناصر مبدا لازم برای ایجاد مخزن هستید.

inject-nmi

ساختار دستوری:

inject-nmi domain

یک NMI را به سیستم‌عامل مهمان تزریق می‌کند.

list

ساختار دستوری:

list [--inactive | --all]
     [--managed-save] [--title]
     { [--table] | --name | --id } [--uuid]
     [--persistent] [--transient]
     [--with-managed-save] [--without-managed-save]
     [--autostart] [--no-autostart]
     [--with-snapshot] [--without-snapshot]
     [--with-checkpoint] [--without-checkpoint]
     [--state-running] [--state-paused]
     [--state-shutoff] [--state-other]

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

مثال ۱:

نمونه‌ای از ساختار خروجی فهرست به صورت زیر است:

``virsh`` list
  Id    Name                           State
----------------------------------------------------
  0     Domain-0                       running
  2     fedora                         paused

مقدار Name نام دامنه است. مقدار ID شناسه عددی دامنه است. مقدار State وضعیت اجرا است (پایین را ببینید).

وضعیت‌ها (STATES)

فیلد State مشخص می‌کند که هر دامنه در حال حاضر در چه وضعیتی قرار دارد. یک دامنه می‌تواند در یکی از وضعیت‌های ممکن زیر باشد:

به‌طور معمول فقط دامنه‌های فعال فهرست می‌شوند. برای فهرست کردن دامنه‌های غیرفعال گزینه --inactive یا --all را برای فهرست کردن هر دو دامنه‌های فعال و غیرفعال مشخص کنید.

فیلتر کردن (Filtering)

برای فیلتر کردن دقیق‌تر فهرست دامنه‌ها می‌توانید یک یا چند پرچم فیلترسازی را که توسط دستور list پشتیبانی می‌شوند مشخص کنید. این پرچم‌ها بر اساس عملکرد گروه‌بندی شده‌اند. مشخص کردن یک یا چند پرچم از یک گروه، آن گروه فیلتر را فعال می‌کند. توجه داشته باشید که برخی از ترکیب‌های پرچم‌ها ممکن است نتیجه‌ای در بر نداشته باشند. پرچم‌ها و گروه‌های فیلترسازی پشتیبانی‌شده:.SS مانایی (Persistence)

پرچم --persistent برای گنجاندن مهمان‌های مانا در فهرست بازگردانده‌شده استفاده می‌شود. برای گنجاندن مهمان‌های گذرا، --transient را مشخص کنید.

وجود تصویر ذخیره‌شده مدیریتی (Existence of managed save image)

برای فهرست کردن دامنه‌هایی که دارای تصویر ذخیره مدیریتی هستند، پرچم --with-managed-save را مشخص کنید. برای دامنه‌هایی که تصویر ذخیره مدیریتی ندارند، --without-managed-save را مشخص کنید.

وضعیت دامنه (Domain state)

پرچم‌های پالایه زیر یک دامنه را بر اساس وضعیت آن انتخاب می‌کنند: --state-running برای دامنه‌های در حال اجرا، --state-paused برای دامنه‌های متوقف‌شده، --state-shutoff برای دامنه‌های خاموش‌شده و --state-other برای همه وضعیت‌های دیگر به عنوان حالت جایگزین.

دامنه‌های با شروع خودکار (Autostarting domains)

برای فهرست کردن دامنه‌هایی با قابلیت شروع خودکار از پرچم --autostart استفاده کنید. برای فهرست کردن دامنه‌هایی که این ویژگی در آن‌ها غیرفعال است از --no-autostart استفاده کنید.

وجود اسنپ‌شات (Snapshot existence)

دامنه‌های دارای تصاویر اسنپ‌شات را می‌توان با پرچم --with-snapshot و دامنه‌های فاقد اسنپ‌شات را با --without-snapshot فهرست کرد.

وجود چک‌پوینت (Checkpoint existence)

دامنه‌های دارای چک‌پوینت را می‌توان با استفاده از پرچم --with-checkpoint و دامنه‌های بدون چک‌پوینت را با --without-checkpoint فهرست کرد.

هنگام ارتباط با کارسازهای قدیمی‌تر، این دستور ناچار است از مجموعه‌ای از فراخوانی‌های API با شرایط رقابتی ذاتی (race condition) استفاده کند؛ وضعیتی که در آن اگر حالت دامنه‌ای بین فراخوانی‌ها در حین جمع‌آوری فهرست تغییر کند، ممکن است در فهرست ظاهر نشود یا بیش از یک بار درج گردد. کارسازهای جدیدتر این مشکل را ندارند.

اگر --managed-save مشخص شود، دامنه‌هایی که دارای وضعیت ذخیره مدیریتی هستند (فقط زمانی ممکن است که در وضعیت shut off باشند، بنابراین برای فهرست کردن واقعی آن‌ها باید --inactive یا --all را مشخص کنید) در فهرست به عنوان saved نمایش داده می‌شوند. این پرچم تنها همراه با خروجی پیش‌فرض --table قابل استفاده است. توجه داشته باشید که این پرچم فهرست دامنه‌ها را پالایش نمی‌کند.

اگر --name مشخص شود، به جای خروجی جدولی، نام دامنه‌ها در هر سطر یکی چاپ می‌شوند. اگر --uuid مشخص شود، به جای نام‌ها، UUIDهای دامنه‌ها چاپ می‌شوند. اگر --id مشخص شود، به جای نام‌ها، IDهای دامنه‌ها چاپ می‌شوند. با این حال، می‌توان --name، --uuid و --id را برای انتخاب فیلدهای دلخواه جهت چاپ با یکدیگر ترکیب کرد. پرچم --table مشخص می‌کند که باید از خروجی سنتی با قالب جدول استفاده شود، اما این گزینه با --name و --id مانعة‌الجمع است. این حالت پیش‌فرض است و در صورتی که هیچ‌کدام از --name، --uuid یا --id مشخص نشده باشند استفاده خواهد شد. اگر نه --name و نه --uuid مشخص نشوند، اما --id مشخص شده باشد، حتی با پارامتر --all تنها دامنه‌های فعال فهرست می‌شوند، چرا که در غیر این صورت خروجی تنها شامل چندین سطر با فقط -1 خواهد بود. اگر --table با --uuid ترکیب شود، UUID دامنه به عنوان یک ستون اضافی چاپ می‌شود.

اگر --title مشخص شود، توضیح کوتاه دامنه (عنوان) در یک ستون اضافی چاپ می‌شود. این پرچم تنها با خروجی پیش‌فرض --table قابل استفاده است.

مثال ۲:

$ virsh list --title
  Id    Name        State      Title
 -------------------------------------------
  0     Domain-0    running    Mailserver 1
  2     fedora      paused

freecell

نحو:

freecell [{ [--cellno] cellno | --all }]

مقدار حافظه دردسترس روی ماشین یا درون یک سلول NUMA را چاپ می‌کند. دستور freecell بسته به گزینه‌های مشخص‌شده می‌تواند یکی از سه حالت نمایش حافظه در دسترس روی ماشین را ارائه دهد. بدون هیچ گزینه‌ای، کل حافظه آزاد روی ماشین را نمایش می‌دهد. با گزینه --all، حافظه آزاد در هر سلول و کل حافظه آزاد روی ماشین را نمایش می‌دهد. در نهایت، با یک آرگومان عددی یا با --cellno به همراه شماره سلول، حافظه آزاد را تنها برای سلول مشخص‌شده نمایش می‌دهد..SS freepages

نحو:

freepages [{ [--cellno] cellno [--pagesize] pagesize |     --all }]

تعداد صفحات دردسترس را در یک سلول NUMA چاپ می‌کند. cellno به سلول NUMA مورد نظر شما اشاره دارد. pagesize یک عدد صحیح مقیاس‌دار است (به NOTES در بالا مراجعه کنید). در غیر این صورت، اگر --all استفاده شود، اطلاعات هر ترکیب ممکن از سلول NUMA و اندازه صفحه چاپ می‌شود.

allocpages

نحو:

allocpages [--pagesize] pagesize [--pagecount] pagecount [[--cellno] cellno] [--add] [--all]

اندازه استخر صفحات با اندازه pagesize را روی میزبان تغییر می‌دهد. اگر --add مشخص شده باشد، تعداد pagecount صفحه به استخر افزوده می‌شود. با این حال، اگر --add مشخص نشده باشد، pagecount به عنوان اندازه مطلق جدید استخر در نظر گرفته می‌شود (این کار می‌تواند برای آزادسازی برخی صفحات و کاهش اندازه استخر استفاده شود). تغییردهنده cellno می‌تواند برای محدود کردن تغییرات به یک سلول NUMA منفرد میزبان استفاده شود. در سمت دیگر طیف، --all قرار دارد که تغییرات را روی همه سلول‌های NUMA اعمال می‌کند.

cpu-baseline

نحو:

cpu-baseline FILE [--features] [--migratable]

محاسبه پردازنده پایه (baseline CPU) که توسط تمام پردازنده‌های میزبان ذکر شده در <file> پشتیبانی خواهد شد. (برای دریافت پردازنده‌ای که می‌تواند توسط یک هایپروایزر خاص ارائه شود، به دستور hypervisor-cpu-baseline مراجعه کنید.) فهرست پردازنده‌های میزبان با استخراج تمام عناصر <cpu> از <file> ساخته می‌شود. بنابراین، <file> می‌تواند شامل مجموعه‌ای از عناصر <cpu> جدا شده با خطوط جدید، یا حتی مجموعه‌ای از عناصر کامل <capabilities> باشد که توسط دستور capabilities چاپ شده است. اگر --features مشخص شود، توصیف XML حاصل به صراحت شامل تمام ویژگی‌هایی خواهد بود که پردازنده را تشکیل می‌دهند؛ بدون این گزینه ویژگی‌هایی که بخشی از مدل پردازنده هستند در توصیف XML فهرست نخواهند شد. اگر --migratable مشخص شود، ویژگی‌هایی که مانع مهاجرت می‌شوند در پردازنده حاصل گنجانده نخواهند شد.

cpu-compare

نحو:

cpu-compare FILE [--error] [--validate]

تعریف پردازنده را از <file> با فرمت XML با پردازنده میزبان مقایسه می‌کند. (برای مقایسه تعریف پردازنده با پردازنده‌ای که یک هایپروایزر خاص قادر است روی میزبان فراهم کند، به دستور hypervisor-cpu-compare مراجعه کنید.) فایل XML می‌تواند شامل تعریف پردازنده میزبان یا مهمان باشد. تعریف پردازنده میزبان، همان عنصر <cpu> و محتویات آن است که توسط دستور capabilities چاپ می‌شود. تعریف پردازنده مهمان، عنصر <cpu> و محتویات آن از تعریف XML دامنه، یا تعریف پردازنده ایجاد شده از مدل پردازنده میزبانِ موجود در XML قابلیت‌های دامنه (چاپ‌شده توسط دستور domcapabilities) است. علاوه بر خودِ عنصر <cpu>، این دستور XML کامل دامنه، XML قابلیت‌ها، یا XML قابلیت‌های دامنه حاوی تعریف پردازنده را می‌پذیرد. برای اطلاعات بیشتر درباره تعریف پردازنده مهمان ببینید: https://libvirt.org/formatdomain.html#elementsCPU https://libvirt.org/formatdomain.html#cpu-model-and-topology. اگر --error مشخص شده باشد، در صورت ناسازگار بودن پردازنده داده‌شده با پردازنده میزبان، دستور خطایی برمی‌گرداند و پیامی حاوی جزئیات بیشتر درباره این ناسازگاری چاپ خواهد شد. اگر --validate مشخص شده باشد، قالب سند XML را در برابر یک شمای RNG داخلی اعتبارسنجی می‌کند..SS cpu-models

نحو:

cpu-models arch

چاپ فهرست مدل‌های CPU شناخته‌شده توسط libvirt برای معماری مشخص‌شده. این که آیا یک هایپروایزر خاص قادر به ایجاد دامنه‌ای است که از هر یک از مدل‌های CPU چاپ‌شده استفاده کند یا خیر، مسئله جداگانه‌ای است که با نگاه کردن به XML قابلیت‌های دامنه بازگردانده‌شده توسط دستور domcapabilities می‌توان به آن پاسخ داد. علاوه بر این، برای برخی معماری‌ها libvirt هیچ مدل CPUای را نمی‌شناسد و مدل‌های CPU قابل استفاده صرفاً توسط هایپروایزر محدود می‌شوند. این دستور چاپ خواهد کرد که تمامی مدل‌های CPU برای این معماری‌ها پذیرفته می‌شوند و فهرست واقعی مدل‌های CPU پشتیبانی‌شده را می‌توان در XML قابلیت‌های دامنه بررسی کرد.

hypervisor-cpu-compare

نحو:

hypervisor-cpu-compare FILE [virttype] [emulator] [arch] [machine] [--error] [--validate]

مقایسه تعریف CPU از <file> مربوط به XML با CPUای که هایپروایزر قادر است روی میزبان ارائه دهد. (این دستور با cpu-compare که تعریف CPU را با CPU میزبان بدون در نظر گرفتن هایپروایزری خاص و توانایی‌های آن مقایسه می‌کند، متفاوت است.)

فایل XML با نام FILE باید شامل یک تعریف CPU مهمان باشد: یا عنصر <cpu> و محتویات آن از یک تعریف XML دامنه، یا یک تعریف CPU ایجادشده از مدل CPU میزبانِ یافت‌شده در عنصر <mode name="host-model"> در XML قابلیت‌های دامنه (چاپ‌شده توسط دستور domcapabilities). خود عنصر <mode name="host-model"> یا حتی عنصر والد آن، <cpu>، که در XML قابلیت‌های دامنه قرار دارد پذیرفته نیست. این عنصر باید به یک تعریف واقعی CPU تبدیل شود. برای اطلاعات بیشتر درباره تعریف CPU مهمان ببینید: https://libvirt.org/formatdomain.html#elementsCPU https://libvirt.org/formatdomain.html#cpu-model-and-topology.

متناوباً، در صورتی که یک XML کامل دامنه یا XML قابلیت‌های دامنه به این دستور ارائه شود، تعریف CPU را به صورت خودکار استخراج خواهد کرد.

به دلایل تاریخی، FILEِ XML ممکن است حاوی یک تعریف CPU میزبان نیز باشد، اما چنین استفاده‌ای اکیداً نهی می‌شود زیرا به احتمال زیاد نتایج نادرستی به همراه خواهد داشت.

گزینه virttype نوع مجازی‌سازی را مشخص می‌کند (قابل استفاده در صفت 'type' از عنصر سطح بالای <domain> در XML دامنه). emulator مسیر شبیه‌ساز را مشخص می‌کند، arch معماری CPU را تعیین می‌نماید، و machine نوع ماشین را مشخص می‌سازد. اگر --error مشخص شده باشد، در صورتی که CPU داده‌شده با CPU میزبان ناسازگار باشد، دستور یک خطا بازمی‌گرداند و پیامی حاوی جزئیات بیشتر درباره این ناسازگاری چاپ خواهد شد. اگر --validate مشخص شده باشد، قالب سند XML را در برابر یک شِمای داخلی RNG اعتبارسنجی می‌کند.

hypervisor-cpu-baseline

نحو:

hypervisor-cpu-baseline [FILE] [virttype] [emulator] [arch] [machine]
   [--features] [--migratable] [--ignore-host] [model]

محاسبه یک CPU مبنا (baseline) که با تمام CPUهای تعریف‌شده در یک FILEِ XML سازگار باشد. این دستور باید روی یکی از میزبان‌های توصیف‌شده در FILE فراخوانی شود. فراخوانی آن روی یک میزبان دیگر منجر به رفتار تعریف‌نشده می‌شود زیرا مدل CPU محاسبه‌شده تحت تأثیر هایپروایزر است (نتیجه ممکن است از یک مدل CPU غیرمنتظره استفاده کند یا برخی ویژگی‌ها غیرفعال شوند، حتی اگر روی تمام CPUهای ورودی پشتیبانی شوند). از این رفتار تعریف‌نشده می‌توان با استفاده از گزینه --ignore-host جلوگیری کرد (پایین‌تر را ببینید).

این دستور با cpu-baseline که هنگام محاسبه CPU مبنا توانایی‌های هایپروایزر را در نظر نمی‌گیرد، متفاوت است.

به عنوان جایگزینی برای FILE، در صورتی که XML فقط شامل یک مدل CPU بدون هیچ ویژگی اضافی باشد، خود نام مدل CPU را می‌توان به عنوان model ارسال کرد. دقیقاً یکی از FILE و model باید استفاده شود.

فایل XML با نام FILE باید حاوی تعاریف CPU مهمان ایجادشده از مدل CPU میزبانِ موجود در عنصر <mode name="host-model"> در XMLهای قابلیت‌های دامنه باشد (که توسط دستور domcapabilities روی هر میزبان چاپ می‌شود). خود عناصر <mode name="host-model"> یا حتی عناصر والد <cpu> آن‌ها در XMLهای قابلیت‌های دامنه پذیرفته نیستند. این عناصر باید به تعاریف واقعی CPU تبدیل شوند.

متناوباً، این دستور هنگامی که XMLهای قابلیت‌های دامنه به آن ارائه شود، تعاریف CPU را به طور خودکار استخراج خواهد کرد.

به دلایل تاریخی، FILEِ XML ممکن است حاوی تعاریف CPU میزبان نیز باشد، اما چنین استفاده‌ای اکیداً نهی می‌شود زیرا به احتمال زیاد نتایج نادرستی ارائه می‌دهد.

هنگامی که FILE تنها شامل یک تعریف CPU باشد، دستور همان CPU را با محدودیت‌های اعمال‌شده توسط قابلیت‌های هایپروایزر چاپ خواهد کرد. به طور خاص، اجرای دستور virsh hypervisor-cpu-baseline بدون گزینه‌های اضافی روی خروجی virsh domcapabilities، مدل CPU میزبان را از XML قابلیت‌های دامنه به قالبی تبدیل می‌کند که مستقیماً در XML دامنه قابل استفاده است. اجرای دستور با model (یا با FILEِ حاوی تنها یک تعریف CPU همراه با مدل و بدون عناصر ویژگی) که در virsh domcapabilities به عنوان غیرقابل استفاده علامت‌گذاری شده است، فهرستی از ویژگی‌هایی را ارائه می‌دهد که مانع از قابل استفاده بودن این مدل CPU می‌شوند.

گزینه virttype نوع مجازی‌سازی را مشخص می‌کند (قابل استفاده در صفت 'type' از عنصر سطح بالای <domain> در XML دامنه). emulator مسیر شبیه‌ساز را مشخص می‌کند، arch معماری CPU را تعیین می‌نماید، و machine نوع ماشین را مشخص می‌سازد. اگر --features مشخص شده باشد، شرح XML حاصل صراحتاً تمام ویژگی‌هایی را که CPU را تشکیل می‌دهند در بر خواهد گرفت؛ بدون این گزینه، ویژگی‌هایی که بخشی از مدل CPU هستند در شرح XML فهرست نخواهند شد. اگر --migratable مشخص شده باشد، ویژگی‌هایی که مانع مهاجرت می‌شوند در CPU حاصل گنجانده نخواهند شد. اگر --ignore-host مشخص شده باشد و FILE شامل بیش از یک CPU باشد، دستور هنگام محاسبه مبنا توانایی‌های هایپروایزر را در نظر نخواهد گرفت. با این گزینه، مبنا را می‌توان با اطمینان روی هر میزبانی (حتی آن‌هایی که در FILE توصیف نشده‌اند) محاسبه کرد..SS hypervisor-cpu-models

نحو:

hypervisor-cpu-models [--virttype virttype] [--emulator emulator]
   [--arch arch] [--machine machine] [--all]

فهرست مدل‌های CPU شناخته‌شده توسط هایپروایزر را برای معماری مشخص‌شده چاپ می‌کند. هیچ تضمینی وجود ندارد که یک CPU فهرست‌شده روی میزبان اجرا شود. برای تعیین سازگاری مدل CPU با میزبان، virsh hypervisor-cpu-baseline و virsh hypervisor-cpu-compare را ببینید.

گزینهٔ virttype نوع مجازی‌سازی را مشخص می‌کند (قابل استفاده در صفت 'type' از عنصر سطح بالای <domain> در XML دامنه). emulator مسیر امولاتور (شبیه‌ساز) را مشخص می‌کند، arch معماری CPU را تعیین می‌کند، و machine نوع ماشین را مشخص می‌نماید.

به‌طور پیش‌فرض، تنها مدل‌هایی گزارش می‌شوند که هایپروایزر ادعا می‌کند روی میزبان «قابل استفاده» ("usable") هستند. گزینهٔ --all تمام مدل‌های CPU شناخته‌شده برای هایپروایزر را گزارش می‌دهد، از جمله مدل‌هایی که روی هایپروایزر پشتیبانی نمی‌شوند (مثلاً مدل‌های نسل جدیدتر).

autostart

نحو:

autostart [--disable] [--once] domain

پیکربندی یک دامنه برای راه‌اندازی خودکار در هر بار بوت میزبان. گزینهٔ --once دامنه را برای راه‌اندازی در بوت بعدی میزبان پیکربندی می‌کند.

گزینهٔ --disable راه‌اندازی خودکار متناظر را غیرفعال می‌کند.

توجه داشته باشید که راه‌اندازی خودکار پیکربندی‌شده از طریق گزینهٔ --once از راه‌اندازی خودکار پیکربندی‌شده بدون آن مستقل است. فعال کردن هر کدام از آن‌ها باعث می‌شود ماشین مجازی (VM) در بوت بعدی میزبان راه‌اندازی شود.

blkdeviotune

نحو:

blkdeviotune domain device [[--config] [--live] | [--current]]
   [[total-bytes-sec] | [read-bytes-sec] [write-bytes-sec]]
   [[total-iops-sec] | [read-iops-sec] [write-iops-sec]]
   [[total-bytes-sec-max] | [read-bytes-sec-max] [write-bytes-sec-max]]
   [[total-iops-sec-max] | [read-iops-sec-max] [write-iops-sec-max]]
   [[total-bytes-sec-max-length] |
    [read-bytes-sec-max-length] [write-bytes-sec-max-length]]
   [[total-iops-sec-max-length] |
    [read-iops-sec-max-length] [write-iops-sec-max-length]]
   [size-iops-sec] [group-name]

تنظیم یا پرس‌وجوی پارامترهای I/O دیسک بلوکی برای یک دستگاه بلوکی از domain. device یک نام هدف یکتا (<target dev='name'/>) یا فایل منبع (<source file='name'/>) را برای یکی از دستگاه‌های دیسک متصل به domain مشخص می‌کند (برای فهرست کردن این نام‌ها همچنین domblklist را ببینید).

اگر هیچ محدودیتی مشخص نشود، تنظیمات محدودیت‌های فعلی I/O را پرس‌وجو می‌کند. در غیر این صورت، محدودیت‌ها را با این پرچم‌ها تغییر دهید: --total-bytes-sec حد کل پهنای باند را به صورت یک عدد صحیح مقیاس‌پذیر مشخص می‌کند؛ در صورتی که پسوندی مشخص نشده باشد، پیش‌فرض بایت بر ثانیه است. --read-bytes-sec حد پهنای باند خواندن را به صورت یک عدد صحیح مقیاس‌پذیر مشخص می‌کند؛ در صورتی که پسوندی مشخص نشده باشد، پیش‌فرض بایت بر ثانیه است. --write-bytes-sec حد پهنای باند نوشتن را به صورت یک عدد صحیح مقیاس‌پذیر مشخص می‌کند؛ در صورتی که پسوندی مشخص نشده باشد، پیش‌فرض بایت بر ثانیه است. --total-iops-sec حد کل عملیات‌های I/O بر ثانیه را مشخص می‌کند. --read-iops-sec حد عملیات‌های خواندن I/O بر ثانیه را مشخص می‌کند. --write-iops-sec حد عملیات‌های نوشتن I/O بر ثانیه را مشخص می‌کند. --total-bytes-sec-max حداکثر حد کل پهنای باند را به صورت یک عدد صحیح مقیاس‌پذیر مشخص می‌کند؛ در صورتی که پسوندی مشخص نشده باشد، پیش‌فرض بایت بر ثانیه است. --read-bytes-sec-max حداکثر حد پهنای باند خواندن را به صورت یک عدد صحیح مقیاس‌پذیر مشخص می‌کند؛ در صورتی که پسوندی مشخص نشده باشد، پیش‌فرض بایت بر ثانیه است. --write-bytes-sec-max حداکثر حد پهنای باند نوشتن را به صورت یک عدد صحیح مقیاس‌پذیر مشخص می‌کند؛ در صورتی که پسوندی مشخص نشده باشد، پیش‌فرض بایت بر ثانیه است. --total-iops-sec-max حداکثر حد کل عملیات‌های I/O بر ثانیه را مشخص می‌کند. --read-iops-sec-max حداکثر حد عملیات‌های خواندن I/O بر ثانیه را مشخص می‌کند. --write-iops-sec-max حداکثر حد عملیات‌های نوشتن I/O بر ثانیه را مشخص می‌کند. --total-bytes-sec-max-length مدت‌زمان بر حسب ثانیه برای مجاز بودن حداکثر حد کل پهنای باند را مشخص می‌کند. --read-bytes-sec-max-length مدت‌زمان بر حسب ثانیه برای مجاز بودن حداکثر حد پهنای باند خواندن را مشخص می‌کند. --write-bytes-sec-max-length مدت‌زمان بر حسب ثانیه برای مجاز بودن حداکثر حد پهنای باند نوشتن را مشخص می‌کند. --total-iops-sec-max-length مدت‌زمان بر حسب ثانیه برای مجاز بودن حداکثر حد کل عملیات‌های I/O را مشخص می‌کند. --read-iops-sec-max-length مدت‌زمان بر حسب ثانیه برای مجاز بودن حداکثر حد عملیات‌های خواندن I/O را مشخص می‌کند. --write-iops-sec-max-length مدت‌زمان بر حسب ثانیه برای مجاز بودن حداکثر حد عملیات‌های نوشتن I/O را مشخص می‌کند. --size-iops-sec حد اندازهٔ عملیات‌های I/O بر ثانیه را مشخص می‌کند. --group-name نام گروه را برای اشتراک سهمیهٔ I/O بین چند درایو مشخص می‌کند. برای یک دامنهٔ QEMU، اگر هیچ نامی ارائه نشود، پیش‌فرض اختصاص یک گروه مجزا برای هر device است.

نسخه‌های قدیمی‌تر virsh این گزینه‌ها را فقط با خط زیر (underscore) به‌جای خط تیره می‌پذیرفتند، مانند --total_bytes_sec.

مقادیر Bytes و iops مستقل از یکدیگرند، اما تنظیم تنها یک مقدار (مانند --read-bytes-sec) دو مقدار دیگر در آن دسته‌بندی را به نامحدود بازنشانی می‌کند. مقدار صریح 0 نیز هر محدودیتی را پاک می‌کند. یک مقدار غیر صفر برای یک total مشخص نمی‌تواند با مقادیر غیر صفر برای read یا write ترکیب شود.

تعیین چگونگی مدیریت مقادیر طول (length) بر عهدهٔ هایپروایزر است. برای هایپروایزر QEMU، اگر یک مقدار محدودیت I/O یا مقدار حداکثر تنظیم شود، مقدار پیش‌فرض ۱ ثانیه نمایش داده خواهد شد. ارائهٔ 0، مقدار را به حالت پیش‌فرض بازمی‌گرداند.

اگر --live مشخص شده باشد، روی یک مهمان در حال اجرا اعمال می‌شود. اگر --config مشخص شده باشد، روی شروع بعدی یک مهمان ماندگار اعمال خواهد شد. اگر --current مشخص شده باشد، بسته به وضعیت فعلی مهمان، معادل --live یا --config خواهد بود. هنگام تنظیم پارامترهای I/O دیسک، می‌توان هر دو پرچم --live و --config را تعیین کرد، اما --current انحصاری است. برای پرس‌وجو، فقط یکی از پرچم‌های --live، --config یا --current می‌تواند مشخص شود. اگر هیچ پرچمی مشخص نشود، رفتار بسته به هایپروایزر متفاوت خواهد بود..SS domthrottlegroupset

نحو:

domthrottlegroupset domain group-name [[--config] [--live] | [--current]]
   [[total-bytes-sec] | [read-bytes-sec] [write-bytes-sec]]
   [[total-iops-sec] | [read-iops-sec] [write-iops-sec]]
   [[total-bytes-sec-max] | [read-bytes-sec-max] [write-bytes-sec-max]]
   [[total-iops-sec-max] | [read-iops-sec-max] [write-iops-sec-max]]
   [[total-bytes-sec-max-length] |
    [read-bytes-sec-max-length] [write-bytes-sec-max-length]]
   [[total-iops-sec-max-length] |
    [read-iops-sec-max-length] [write-iops-sec-max-length]]
   [size-iops-sec]

افزودن یا به‌روزرسانی یک throttle group برای domain مشخص‌شده. group-name یک نام یکتای throttle group را مشخص می‌کند که محدودیت را تعیین کرده و توسط درایوها مورد ارجاع قرار خواهد گرفت.

اگر هیچ محدودیتی مشخص نشود، به صورت پیش‌فرض تمام آن‌ها صفر در نظر گرفته می‌شوند که ناموفق خواهد بود؛ در غیر این صورت، محدودیت‌ها را با این پرچم‌ها تنظیم کنید: --total-bytes-sec حد توان عملیاتی کل را به صورت یک عدد صحیح مقیاس‌دار مشخص می‌کند، که در صورت تعیین نشدن پسوند، پیش‌فرض بایت بر ثانیه است. --read-bytes-sec حد توان عملیاتی خواندن را به صورت یک عدد صحیح مقیاس‌دار مشخص می‌کند، که در صورت تعیین نشدن پسوند، پیش‌فرض بایت بر ثانیه است. --write-bytes-sec حد توان عملیاتی نوشتن را به صورت یک عدد صحیح مقیاس‌دار مشخص می‌کند، که در صورت تعیین نشدن پسوند، پیش‌فرض بایت بر ثانیه است. --total-iops-sec حد کل عملیات I/O در ثانیه را مشخص می‌کند. --read-iops-sec حد عملیات خواندن I/O در ثانیه را مشخص می‌کند. --write-iops-sec حد عملیات نوشتن I/O در ثانیه را مشخص می‌کند. --total-bytes-sec-max حداکثر حد توان عملیاتی کل را به صورت یک عدد صحیح مقیاس‌دار مشخص می‌کند، که در صورت تعیین نشدن پسوند، پیش‌فرض بایت بر ثانیه است. --read-bytes-sec-max حداکثر حد توان عملیاتی خواندن را به صورت یک عدد صحیح مقیاس‌دار مشخص می‌کند، که در صورت تعیین نشدن پسوند، پیش‌فرض بایت بر ثانیه است. --write-bytes-sec-max حداکثر حد توان عملیاتی نوشتن را به صورت یک عدد صحیح مقیاس‌دار مشخص می‌کند، که در صورت تعیین نشدن پسوند، پیش‌فرض بایت بر ثانیه است. --total-iops-sec-max حداکثر حد کل عملیات I/O در ثانیه را مشخص می‌کند. --read-iops-sec-max حداکثر حد عملیات خواندن I/O در ثانیه را مشخص می‌کند. --write-iops-sec-max حداکثر حد عملیات نوشتن I/O در ثانیه را مشخص می‌کند. --total-bytes-sec-max-length مدت‌زمان بر حسب ثانیه را برای مجاز بودن حداکثر حد توان عملیاتی کل مشخص می‌کند. --read-bytes-sec-max-length مدت‌زمان بر حسب ثانیه را برای مجاز بودن حداکثر حد توان عملیاتی خواندن مشخص می‌کند. --write-bytes-sec-max-length مدت‌زمان بر حسب ثانیه را برای مجاز بودن حداکثر حد توان عملیاتی نوشتن مشخص می‌کند. --total-iops-sec-max-length مدت‌زمان بر حسب ثانیه را برای مجاز بودن حداکثر حد کل عملیات I/O مشخص می‌کند. --read-iops-sec-max-length مدت‌زمان بر حسب ثانیه را برای مجاز بودن حداکثر حد عملیات خواندن I/O مشخص می‌کند. --write-iops-sec-max-length مدت‌زمان بر حسب ثانیه را برای مجاز بودن حداکثر حد عملیات نوشتن I/O مشخص می‌کند. --size-iops-sec حد اندازه عملیات I/O در ثانیه را مشخص می‌کند.

مقادیر Bytes و iops مستقل از یکدیگرند، اما تنظیم فقط یک مقدار (مانند --read-bytes-sec) دو مقدار دیگر در آن دسته‌بندی را به نامحدود بازنشانی می‌کند. یک مقدار صریح 0 نیز هرگونه محدودیتی را پاک می‌کند. یک مقدار غیرصفر برای مقدار کل داده‌شده نمی‌تواند با مقادیر غیرصفر برای خواندن یا نوشتن ترکیب شود.

نحوه مدیریت مقادیر طول مدت (length) بر عهده هایپروایزر است. برای هایپروایزر QEMU، اگر یک مقدار حد I/O یا مقدار بیشینه تنظیم شود، مقدار پیش‌فرض ۱ ثانیه نمایش داده خواهد شد. وارد کردن مقدار 0 آن را به مقدار پیش‌فرض بازنشانی خواهد کرد.

اگر --live مشخص شود، بر روی مهمان در حال اجرا اثر می‌گذارد. اگر --config مشخص شود، بر راه‌اندازی بعدی یک مهمان ماندگار اثر می‌گذارد. اگر --current مشخص شود، بسته به وضعیت فعلی مهمان، معادل --live یا --config خواهد بود. هنگام تنظیم پارامترهای io دیسک چنانچه هر دو گزینه --live و --config مشخص شوند، هم پیکربندی زنده و هم config به‌روزرسانی می‌شوند، اما --current انحصاری است. اگر هیچ پرچمی مشخص نشود، رفتار بسته به هایپروایزر متفاوت خواهد بود.

domthrottlegroupdel

نحو:

domthrottlegroupdel domain group-name [[--config] [--live] | [--current]]

یک Throttlegroup را با استفاده از group-name مشخص‌شده از domain حذف می‌کند. اگر یک Throttlegroup در حال حاضر توسط یک منبع دیسک مورد ارجاع باشد، تلاش برای حذف آن ناموفق خواهد بود. اگر group-name وجود نداشته باشد، خطایی رخ خواهد داد.

اگر --live مشخص شود، بر روی مهمان در حال اجرا اثر می‌گذارد. اگر مهمان در حال اجرا نباشد، یک خطا برگردانده می‌شود. اگر --config مشخص شود، بر راه‌اندازی بعدی یک مهمان ماندگار اثر می‌گذارد. اگر --current مشخص شود، بسته به وضعیت فعلی مهمان، معادل --live یا --config خواهد بود..SS domthrottlegroupinfo

نحو:

domthrottlegroupinfo domain group-name [[--config] [--live] | [--current]]

نمایش اطلاعات Throttlegroup دامنه شامل تنظیمات محدودیت‌های I/O.

اگر --live مشخص شده باشد، داده‌های Throttlegroup از مهمان در حال اجرا دریافت می‌شود. اگر مهمان در حال اجرا نباشد، خطایی بازگردانده می‌شود. اگر --config مشخص شده باشد، داده‌های Throttlegroup از راه‌اندازی بعدی یک مهمان ماندگار (persistent) دریافت می‌شود. اگر --current مشخص شده باشد یا --live و --config تعیین نشده باشند، داده‌های Throttlegroup بر اساس وضعیت فعلی مهمان دریافت می‌شود که می‌تواند زنده یا آفلاین باشد. اگر هر دو گزینهٔ --live و --config مشخص شده باشند، گزینهٔ --config در دریافت توصیف فعلی اولویت خواهد داشت.

domthrottlegrouplist

نحو:

domthrottlegrouplist domain [--inactive]

چاپ جدولی شامل نام‌های تمام throttle groups مرتبط با domain. اگر --inactive مشخص شده باشد، داده‌های Throttlegroup که در بوت بعدی استفاده خواهند شد استعلام می‌شوند، به جای مواردی که هم‌اکنون توسط دامنهٔ در حال اجرا استفاده می‌شوند.

blkiotune

نحو:

blkiotune domain [--weight weight] [--device-weights device-weights]
   [--device-read-iops-sec device-read-iops-sec]
   [--device-write-iops-sec device-write-iops-sec]
   [--device-read-bytes-sec device-read-bytes-sec]
   [--device-write-bytes-sec device-write-bytes-sec]
   [[--config] [--live] | [--current]]

نمایش یا تنظیم پارامترهای blkio. نرم‌افزار QEMU/KVM از --weight پشتیبانی می‌کند. --weight در بازهٔ [100, 1000] قرار دارد. پس از کرنل 2.6.39، مقدار می‌تواند در بازهٔ [10, 1000] باشد.

device-weights رشته‌ای تکی است که یک یا چند جفت دستگاه/وزن را با قالب /path/to/device,weight,/path/to/device,weight فهرست می‌کند. هر وزن در بازهٔ [100, 1000]، یا پس از کرنل 2.6.39 در بازهٔ [10, 1000]، یا مقدار 0 برای حذف آن دستگاه از فهرست‌های مبتنی بر دستگاه است. تنها دستگاه‌های فهرست‌شده در این رشته تغییر می‌یابند؛ هرگونه وزن‌های مبتنی بر دستگاهِ موجود برای سایر دستگاه‌ها بدون تغییر باقی می‌مانند.

device-read-iops-sec رشته‌ای تکی است که یک یا چند جفت device/read_iops_sec را با قالب /path/to/device,read_iops_sec,/path/to/device,read_iops_sec فهرست می‌کند. هر read_iops_sec عددی از نوع unsigned int است، با مقدار 0 برای حذف آن دستگاه از فهرست مبتنی بر دستگاه. تنها دستگاه‌های فهرست‌شده در این رشته تغییر می‌یابند؛ هرگونه read_iops_sec مبتنی بر دستگاهِ موجود برای سایر دستگاه‌ها بدون تغییر باقی می‌مانند.

device-write-iops-sec رشته‌ای تکی است که یک یا چند جفت device/write_iops_sec را با قالب /path/to/device,write_iops_sec,/path/to/device,write_iops_sec فهرست می‌کند. هر write_iops_sec عددی از نوع unsigned int است، با مقدار 0 برای حذف آن دستگاه از فهرست مبتنی بر دستگاه. تنها دستگاه‌های فهرست‌شده در این رشته تغییر می‌یابند؛ هرگونه write_iops_sec مبتنی بر دستگاهِ موجود برای سایر دستگاه‌ها بدون تغییر باقی می‌مانند.

device-read-bytes-sec رشته‌ای تکی است که یک یا چند جفت device/read_bytes_sec را با قالب /path/to/device,read_bytes_sec,/path/to/device,read_bytes_sec فهرست می‌کند. هر read_bytes_sec عددی از نوع unsigned long long است، با مقدار 0 برای حذف آن دستگاه از فهرست مبتنی بر دستگاه. تنها دستگاه‌های فهرست‌شده در این رشته تغییر می‌یابند؛ هرگونه read_bytes_sec مبتنی بر دستگاهِ موجود برای سایر دستگاه‌ها بدون تغییر باقی می‌مانند.

device-write-bytes-sec رشته‌ای تکی است که یک یا چند جفت device/write_bytes_sec را با قالب /path/to/device,write_bytes_sec,/path/to/device,write_bytes_sec فهرست می‌کند. هر write_bytes_sec عددی از نوع unsigned long long است، با مقدار 0 برای حذف آن دستگاه از فهرست مبتنی بر دستگاه. تنها دستگاه‌های فهرست‌شده در این رشته تغییر می‌یابند؛ هرگونه write_bytes_sec مبتنی بر دستگاهِ موجود برای سایر دستگاه‌ها بدون تغییر باقی می‌مانند.

اگر --live مشخص شده باشد، روی مهمان در حال اجرا اثر می‌گذارد. اگر --config مشخص شده باشد، بر راه‌اندازی بعدی یک مهمان ماندگار اثر می‌گذارد. اگر --current مشخص شده باشد، بسته به وضعیت فعلی مهمان، معادل --live یا --config خواهد بود. هر دو پرچم --live و --config می‌توانند با هم داده شوند، اما --current مانعة‌الجمع است. اگر هیچ پرچمی مشخص نشود، رفتار بسته به هایپروایزر متفاوت خواهد بود..SS blockcommit

شکل دستور:

blockcommit domain path [bandwidth] [--bytes] [base]
   [--shallow] [top] [--delete] [--keep-relative]
   [--wait [--async] [--verbose]] [--timeout seconds]
   [--active] [{--pivot | --keep-overlay}]

کاهش طول زنجیرهٔ تصویر پشتیبان (backing image chain)، با اعمال کردن (commit) تغییرات در بالای زنجیره (فایل‌های snapshot یا دلتا) به درون تصاویر پشتیبان. به‌طور پیش‌فرض، این دستور تلاش می‌کند کل زنجیره را یکدست (flatten) کند. اگر base و/یا top به‌عنوان فایل‌هایی در زنجیرهٔ پشتیبان مشخص شوند، عملیات به اعمال فقط همان بخش از زنجیره محدود می‌شود؛ می‌توان به‌جای base از --shallow برای مشخص کردن فایل پشتیبانِ بی‌واسطهٔ تصویر بالای نهایی که قرار است اعمال شود، استفاده کرد. فایل‌هایی که اعمال می‌شوند نامعتبر می‌شوند، احتمالاً به محض شروع عملیات؛ استفاده از پرچم --delete تلاش خواهد کرد این فایل‌های نامعتبر شده را پس از اتمام موفقیت‌آمیز عملیات اعمال حذف کند. هنگامی که پرچم --keep-relative استفاده شود، مسیرهای فایل‌های پشتیبان به‌صورت نسبی حفظ خواهند شد.

هنگامی که top حذف شود یا به‌عنوان تصویر فعال (active image) مشخص شود، همچنین می‌توان --active را برای راه‌اندازی یک اعمال فعال دوفازی مشخص کرد. در فاز اول، top در base کپی می‌شود و کار (job) فقط می‌تواند لغو شود، در حالی که top هنوز حاوی داده‌هایی است که در base وجود ندارند. در فاز دوم، top و base یکسان باقی می‌مانند تا زمانی که فراخوانی به blockjob با پرچم --abort (نگه‌داشتن top به‌عنوان تصویر فعال که تغییرات را از آن نقطهٔ زمانی ردیابی می‌کند) یا پرچم --pivot (تبدیل base به تصویر فعال جدید و نامعتبر کردن top) انجام شود.

به‌طور پیش‌فرض، این دستور در سریع‌ترین زمان ممکن بازمی‌گردد و داده‌های کل دیسک در پس‌زمینه اعمال می‌شوند؛ پیشرفت عملیات را می‌توان با blockjob بررسی کرد. با این حال، اگر --wait مشخص شده باشد، این دستور تا زمان تکمیل عملیات (یا برای --active، تا زمان ورود به فاز دوم)، یا تا زمانی که عملیات به دلیل پایان مهلت زمانی اختیاری timeout (به ثانیه) لغو شود یا SIGINT ارسال شود (معمولاً با Ctrl-C)، متوقف (block) خواهد شد. استفاده از --verbose به همراه --wait به‌روزرسانی‌های دوره‌ای وضعیت را ارائه می‌دهد. در صورت لغو کار، --async کنترل را در سریع‌ترین زمان ممکن به کاربر بازمی‌گرداند، در غیر این صورت ممکن است دستور کمی بیشتر مسدود بماند تا عملیات پاک‌سازی کار به پایان برسد. استفاده از --pivot کوته‌نوشتی برای ترکیب --active --wait با اجرای خودکار blockjob --pivot است؛ و استفاده از --keep-overlay کوته‌نوشتی برای ترکیب --active --wait با اجرای خودکار blockjob --abort است.

پارامتر path مسیر کامل دیسک را مشخص می‌کند؛ این مقدار با یک نام هدف یکتا (<target dev='name'/>) یا فایل منبع (<source file='name'/>) برای یکی از دستگاه‌های دیسک متصل به domain مطابقت دارد (همچنین برای فهرست کردن این نام‌ها domblklist را ببینید). bandwidth محدودیت پهنای باند کپی را بر حسب MiB/s مشخص می‌کند، اگرچه برای QEMU، ممکن است تنها برای یک دامنهٔ برخط (online) غیر صفر باشد. برای اطلاعات بیشتر دربارهٔ آرگومان bandwidth بخش مربوط به دستور blockjob را ببینید.

blockcopy

شکل دستور:

blockcopy domain path { dest [format] [--blockdev] | --xml file }
   [--shallow] [--reuse-external] [bandwidth]
   [--wait [--async] [--verbose]] [{--pivot | --finish}]
   [--timeout seconds] [granularity] [buf-size] [--bytes]
   [--transient-job] [--synchronous-writes] [--dest-is-zero] [--print-xml]

کپی کردن یک زنجیرهٔ تصویر پشتیبان دیسک به یک مقصد. یا dest به‌عنوان نام فایل مقصد، یا --xml با نام یک فایل XML حاوی یک عنصر سطح بالای <disk> که مقصد را توصیف می‌کند، باید ارائه شود. علاوه بر این، اگر dest داده شود، format باید برای تعیین قالب مقصد مشخص گردد (اگر format حذف شود، libvirt از قالب مبدا مجدداً استفاده خواهد کرد، یا با --reuse-external مجبور به کاوش (probe) قالب مقصد خواهد شد، که می‌تواند یک رخنهٔ امنیتی بالقوه باشد). این دستور از --raw به‌عنوان یک پرچم بولی مترادف با --format=raw پشتیبانی می‌کند. هنگام استفاده از dest، مقصد به‌عنوان یک فایل معمولی در نظر گرفته می‌شود مگر اینکه از --blockdev برای مشخص کردن اینکه یک دستگاه بلوکی است استفاده شود. به‌طور پیش‌فرض، این دستور کل زنجیره را یکدست (flatten) می‌کند؛ اما اگر --shallow مشخص شده باشد، نسخهٔ کپی‌شده زنجیرهٔ پشتیبان را به اشتراک می‌گذارد.

اگر --reuse-external مشخص شده باشد، مقصد باید وجود داشته و فضای کافی برای نگهداری نسخهٔ کپی داشته باشد. اگر --shallow به همراه --reuse-external استفاده شود، تصویر از پیش ایجاد شده باید محتویاتی قابل مشاهده برای سیستم‌عامل مهمان داشته باشد که دقیقاً با محتویات قابل مشاهده برای مهمان در فایل پشتیبانِ تصویر اصلی یکسان باشد. این ویژگی می‌تواند برای تغییر نام‌های فایل پشتیبان در مقصد استفاده شود.

به‌طور پیش‌فرض، کار کپی در پس‌زمینه اجرا می‌شود و شامل دو فاز است. در ابتدا، کار باید تمام داده‌ها را از مبدا کپی کند، و در طول این فاز، کار تنها می‌تواند لغو شود تا به دیسک مبدا بازگردد، بدون هیچ تضمینی دربارهٔ مقصد. پس از اتمام این فاز، هم مبدا و هم مقصد به‌صورت آینه‌ای (mirrored) باقی می‌مانند تا زمانی که فراخوانی به blockjob با پرچم‌های --abort و --pivot کار را به مقصد منتقل کند (pivot)، یا فراخوانی بدون --pivot مقصد را به‌عنوان یک نسخهٔ کپی وفادار از آن نقطهٔ زمانی باقی بگذارد. با این حال، اگر --wait مشخص شده باشد، این دستور تا زمان شروع فاز آینه‌سازی متوقف (block) می‌شود، یا اگر timeout اختیاری به ثانیه سپری شود یا SIGINT ارسال شود (معمولاً با Ctrl-C)، عملیات لغو خواهد شد. استفاده از --verbose به همراه --wait گزارش‌های دوره‌ای وضعیت را ارائه می‌دهد. استفاده از --pivot (مشابه blockjob --pivot) یا --finish (مشابه blockjob --abort) مستلزم --wait است، و علاوه بر این کار را به‌طور تمیز پایان می‌دهد به‌جای اینکه آن را در فاز آینه‌سازی رها کند. اگر لغو کار به‌وسیلهٔ مهلت زمانی یا --finish فعال شود، --async کنترل را در سریع‌ترین زمان ممکن به کاربر بازمی‌گرداند، در غیر این صورت ممکن است دستور کمی بیشتر مسدود بماند تا کار واقعاً لغو شود.

پارامتر path مسیر کامل دیسک را مشخص می‌کند. bandwidth محدودیت پهنای باند کپی را بر حسب MiB/s مشخص می‌کند. مشخص کردن یک مقدار منفی به‌عنوان یک مقدار unsigned long long تفسیر می‌شود که ممکن است اساساً نامحدود باشد، اما احتمال سرریز شدن (overflow) آن بیشتر است؛ ایمن‌تر است که برای این منظور از 0 استفاده شود. برای اطلاعات بیشتر در مورد آرگومان bandwidth بخش مربوط به دستور blockjob را ببینید. مشخص کردن granularity امکان تنظیم دقیق دانه‌بندی کپی هنگام شناسایی یک ناحیهٔ تغییریافته (dirty region) را فراهم می‌کند؛ مقادیر بزرگتر بار کاری ورودی/خروجی (I/O) کمتری ایجاد می‌کنند اما ممکن است در کل منجر به کپی شدن داده‌های بیشتری شوند (مقدار پیش‌فرض معمولاً صحیح است)؛ ممکن است هایپروایزرها این مقدار را به توانی از عدد دو محدود کنند یا آن را در محدودهٔ خاصی قرار دهند. مشخص کردن buf-size کنترل می‌کند که چه مقدار داده می‌تواند در طول کپی به‌طور همزمان در جریان (in-flight) باشد؛ مقادیر بزرگتر حافظهٔ بیشتری مصرف می‌کنند اما ممکن است سرعت تکمیل کار را افزایش دهند (مقدار پیش‌فرض معمولاً صحیح است).

گزینهٔ --transient-job این امکان را فراهم می‌کند که مشخص شود در صورت خرابی ماشین مجازی (VM) یا خاموش شدن آن قبل از اتمام کار، نیازی به بازیابی کار توسط کاربر نیست. اگر هایپروایزر محدودیت اجرای کارهای کپی را فقط برای دامنه‌های گذرا (transient domains) اعمال کند، این پرچم آن محدودیت را حذف می‌کند.

اگر --synchronous-writes مشخص شود، کار بلوکی منتظر می‌ماند تا عملیات نوشتن مهمان هم به تصویر اصلی و هم به مقصد کپی منتشر شود تا تضمین گردد که در صورت کندتر بودن فضای ذخیره‌سازی مقصد، کار کپی همگرا خواهد شد. این ممکن است در حین اجرای blockjob بر عملکرد نوشتن‌ها تأثیر منفی بگذارد.

اگر --dest-is-zero مشخص شود، هایپروایزر ممکن است فرض کند که تصویر مقصد از قبل پاک شده است (خواندن از هر آفستی بایت‌های 0x00 برمی‌گرداند) و بنابراین ممکن است از پاک‌سازی اولیهٔ آن صرف‌نظر کند.

اگر --print-xml مشخص شود، به‌جای شروع کار، کد XML استفاده‌شده برای آغاز کار کپی بلوکی چاپ می‌شود..SS blockjob

نحو:

blockjob domain path { [--abort] [--async] [--pivot] |
   [--info] [--raw] [--bytes] | [bandwidth] }

مدیریت عملیات فعال بلوکی. سه حالت مانعة‌الجمع وجود دارد: --info، bandwidth، و --abort. گزینه‌های --async و --pivot به معنای حالت abort هستند؛ --raw به معنای حالت info است؛ و اگر هیچ حالتی مشخص نشود، حالت --info فرض می‌شود.

آرگومان path مسیر کامل دیسک را مشخص می‌کند؛ این مقدار با یک نام هدف یکتا (<target dev='name'/>) یا فایل منبع (<source file='name'/>) برای یکی از دستگاه‌های دیسک متصل به domain مطابقت دارد (برای مشاهده فهرست این نام‌ها، domblklist را نیز ببینید).

در حالت --abort، کار فعال روی دیسک مشخص‌شده لغو خواهد شد. اگر --async نیز مشخص شده باشد، این دستور به‌جای انتظار برای تکمیل لغو، فوراً بازمی‌گردد. اگر --pivot مشخص شده باشد، درخواست می‌کند که یک کار کپی فعال یا commit فعال به تصویر جدید منتقل (pivot) شود.

در حالت --info، اطلاعات کار فعال روی دیسک مشخص‌شده چاپ خواهد شد. به‌طور پیش‌فرض، خروجی یک خط خلاصه خوانا برای انسان است؛ ممکن است این قالب در نسخه‌های آینده تغییر کند. افزودن --raw هر فیلد از ساختار داده را در قالبی پایدار فهرست می‌کند. اگر پرچم --bytes تنظیم شده باشد، در صورتی که سرور نتواند دقت bytes/s را فراهم کند، دستور با خطا مواجه می‌شود؛ هنگام صرف‌نظر کردن از این پرچم، خروجی خام برحسب MiB/s فهرست شده و خروجی خوانا برای انسان به‌طور خودکار بهترین وضوح پشتیبانی‌شده توسط سرور را انتخاب می‌کند.

آرگومان bandwidth می‌تواند برای تعیین محدودیت پهنای باند کار فعال برحسب MiB/s استفاده شود. اگر --bytes مشخص شده باشد، مقدار پهنای باند برحسب bytes/s تفسیر می‌شود. مشخص کردن یک مقدار منفی به‌صورت یک مقدار unsigned long یا اساساً نامحدود تفسیر می‌شود. hypervisor می‌تواند رد کردن مقدار یا تبدیل آن به حداکثر مقدار مجاز را انتخاب کند. به‌صورت اختیاری می‌توان از یک عدد مثبت مقیاس‌بندی‌شده به عنوان پهنای باند استفاده کرد (بخش NOTES در بالا را ببینید). استفاده از --bytes با یک مقدار مقیاس‌بندی‌شده، امکان انتخاب دقت و تفکیک‌پذیری بهتری را فراهم می‌کند. یک مقدار مقیاس‌بندی‌شده بدون --bytes به سمت پایین به MiB/s گرد خواهد شد. توجه داشته باشید که ممکن است --bytes توسط hypervisor پشتیبانی نشود.

توجه داشته باشید که پیشرفت گزارش‌شده برای blockjobهای مربوط به پشتیبان‌گیری pull-mode، نشان‌دهنده پیشرفت پشتیبان‌گیری نیست، بلکه میزان استفاده از فضای موقت مورد نیاز برای پشتیبان‌گیری است.

blockpull

نحو:

blockpull domain path [bandwidth] [--bytes] [base]
   [--wait [--verbose] [--timeout seconds] [--async]]
   [--keep-relative]

پر کردن داده‌های یک دیسک از زنجیره تصاویر پشتیبان (backing image chain) آن. به‌طور پیش‌فرض، این دستور کل زنجیره را مسطح (flatten) می‌کند؛ اما اگر base مشخص شده باشد و شامل نام یکی از فایل‌های پشتیبان در زنجیره باشد، آن فایل به فایل پشتیبان جدید تبدیل شده و تنها بخش میانی زنجیره کشیده (pull) می‌شود. پس از اینکه تمام داده‌های درخواستی از زنجیره تصاویر پشتیبان کشیده شدند، دیسک دیگر به آن بخش از زنجیره پشتیبان وابسته نخواهد بود.

به‌طور پیش‌فرض، این دستور در سریع‌ترین زمان ممکن بازمی‌گردد و داده‌های کل دیسک در پس‌زمینه کشیده می‌شوند؛ پیشرفت عملیات را می‌توان با blockjob بررسی کرد. با این حال، اگر --wait مشخص شده باشد، این دستور تا زمان تکمیل عملیات مسدود خواهد شد، یا در صورتی که زمان اختیاری timeout به ثانیه سپری شود یا سیگنال SIGINT ارسال شود (معمولاً با Ctrl-C)، عملیات را لغو می‌کند. استفاده از --verbose همراه با --wait، وضعیت را به‌صورت دوره‌ای به‌روزرسانی می‌کند. اگر لغو کار فعال شود، --async کنترل را در سریع‌ترین زمان ممکن به کاربر بازمی‌گرداند، در غیر این صورت ممکن است دستور تا پایان پاک‌سازی کار، اندکی بیشتر در حالت مسدود بماند.

استفاده از پرچم --keep-relative نام‌های زنجیره پشتیبان را به‌صورت نسبی نگه می‌دارد.

آرگومان path مسیر کامل دیسک را مشخص می‌کند؛ این مقدار با یک نام هدف یکتا (<target dev='name'/>) یا فایل منبع (<source file='name'/>) برای یکی از دستگاه‌های دیسک متصل به domain مطابقت دارد (برای مشاهده فهرست این نام‌ها، domblklist را نیز ببینید). bandwidth محدودیت پهنای باند کپی را برحسب MiB/s مشخص می‌کند. برای اطلاعات بیشتر در مورد آرگومان bandwidth بخش مربوط به دستور blockjob را ببینید..SS blockresize

نحو:

blockresize domain path ([size] | [--capacity]) [--extend]

تغییر اندازه یک دستگاه بلوکی متعلق به domain در حین اجرای دامنه؛ path مسیر مطلق دستگاه بلوکی را مشخص می‌کند؛ این مقدار با یک نام هدف یکتا (<target dev='name'/>) یا فایل منبع (<source file='name'/>) برای یکی از دستگاه‌های دیسک متصل به domain مطابقت دارد (همچنین برای فهرست کردن این نام‌ها domblklist را ببینید).

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

برای قالب‌های ایمیج فاقد فراداده (raw) ذخیره‌شده درون فضاهای ذخیره‌سازی با اندازه ثابت (مانند دستگاه‌های بلوکی)، می‌توان از پرچم --capacity برای تغییر اندازه دستگاه به اندازه کامل دستگاه پشتیبان استفاده کرد.

مقدار size یک عدد صحیح مقیاس‌پذیر است (بخش NOTES در بالا را ببینید) که در صورت نبود پسوند، پیش‌فرض آن KiB (بلوک‌های ۱۰۲۴ بایتی) است. برای مشخص کردن بایت باید از پسوند "B" استفاده کنید (توجه داشته باشید که به دلایل تاریخی، این رفتار با vol-resize که بدون پسوند به طور پیش‌فرض بر حسب بایت عمل می‌کند، متفاوت است).

console

نحو:

console domain [devname] [--safe] [--force] [--resume]

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

اگر پرچم --safe مشخص شده باشد، تلاش برای اتصال تنها در صورتی انجام می‌شود که درایور از مدیریت امن کنسول پشتیبانی کند. این پرچم مشخص می‌کند که سرور باید دسترسی اختصاصی به دستگاه‌های کنسول را تضمین نماید. به صورت اختیاری می‌توان پرچم --force را برای درخواست قطع هرگونه نشست موجود، مانند مواردی که اتصال قطع شده، مشخص کرد.

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

cpu-stats

نحو:

cpu-stats domain [--total] [start] [count]

ارائه اطلاعات آماری پردازنده (cpu) یک دامنه. دامنه باید در حال اجرا باشد. به طور پیش‌فرض، آمار تمامی پردازنده‌ها و مجموع کل نمایش داده می‌شود. از --total فقط برای دریافت آمار کل، از start فقط برای دریافت آمار پردازنده‌ها به ازای هر CPU از شماره start به بعد، و از count فقط برای آمار به تعداد count پردازنده استفاده کنید.

create

نحو:

create FILE [--console] [--paused] [--autodestroy]
   [--pass-fds N,M,...] [--validate] [--reset-nvram]

ایجاد یک دامنه از یک <file> با قالب XML. به صورت اختیاری، گزینه --validate می‌تواند برای اعتبارسنجی قالب فایل XML ورودی در برابر شِمای RNG داخلی ارسال شود (مشابه با استفاده از ابزار virt-xml-validate(1)). دامنه‌های ایجادشده با این دستور یا گذرا (transient) خواهند بود (موارد موقتی که پس از نابود شدن از بین می‌روند) یا مهمان‌های پایدار (persistent) موجود که با یک پیکربندی یک‌بارمصرف اجرا می‌شوند، در حالی که XML پایدار آن‌ها دست‌نخورده باقی می‌ماند (این قابلیت هنگام آزمایش خودکار پیکربندی‌های گوناگون بر پایه XML اصلی بسیار کاربردی است). برای مشاهده نحوه استفاده، مثال زیر را ببینید.

اگر گزینه --paused استفاده شود و توسط درایور پشتیبانی گردد، دامنه در وضعیت مکث قرار می‌گیرد؛ در غیر این صورت در حال اجرا خواهد بود. اگر --console درخواست شده باشد، پس از ایجاد به کنسول متصل می‌شود. اگر --autodestroy درخواست شده باشد، زمانی که virsh اتصال خود را به libvirt ببندد یا به هر طریق دیگری خارج شود، مهمان به طور خودکار نابود خواهد شد.

اگر --pass-fds مشخص شود، آرگومان آن فهرستی جداشده با کاما از توصیف‌کننده‌های فایل (file descriptors) باز است که باید به مهمان منتقل شوند. شماره توصیف‌کننده‌های فایل در مهمان تغییر کرده و از ۳ شماره‌گذاری مجدد می‌شوند. این مورد فقط در مجازی‌سازی مبتنی بر کانتینر پشتیبانی می‌شود.

اگر --reset-nvram مشخص شود، هرگونه فایل NVRAM/varstore موجود حذف شده و از روی الگوی اولیه و دست‌نخورده آن مجدداً مقداردهی اولیه خواهد شد.

مثال:

# virsh dumpxml <domain> > domain.xml

# $EDITOR domain.xml

# virsh create domain.xml

define FILE [--validate]

desc

نحو:

desc domain [[--live] [--config] |
   [--current]] [--title] [--edit] [--new-desc
   New description or title message]

نمایش یا ویرایش توضیحات و عنوان یک دامنه. این مقادیر فیلدهای کاربری هستند که امکان ذخیره داده‌های متنی اختیاری را برای شناسایی آسان دامنه‌ها فراهم می‌کنند. عنوان باید کوتاه باشد، اگرچه این موضوع اجباری نیست. (همچنین metadata را ببینید که با متاداده‌های بر پایه XML دامنه کار می‌کند.)

پرچم‌های --live یا --config تعیین می‌کنند که این دستور بر روی تعاریف زنده یا پایدار دامنه عمل کند. اگر هر دو گزینه --live و --config مشخص شده باشند، هنگام دریافت توضیحات فعلی، گزینه --config اولویت خواهد داشت و در زمان تنظیم توضیحات، هم پیکربندی زنده و هم config به‌روزرسانی می‌شوند. --current مانعه‌الجمع است و اگر هیچ‌کدام از این موارد مشخص نشده باشند، به صورت ضمنی در نظر گرفته می‌شود.

پرچم --edit مشخص می‌کند که یک ویرایشگر حاوی محتوای توضیحات یا عنوان فعلی باز شود و محتویات پس از ویرایش مجدداً ذخیره شوند.

پرچم --title به جای توضیحات، عملیات را بر روی فیلد عنوان انتخاب می‌کند.

اگر هیچ‌یک از گزینه‌های --edit و --new-desc مشخص نشده باشند، یادداشت یا توضیحات به جای ویرایش شدن، نمایش داده می‌شوند.

destroy

نحو:

destroy domain [--graceful] [--remove-logs]

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

اگر domain گذرا باشد، متاداده‌های هرگونه تصویر لحظه‌ای (snapshot) پس از متوقف شدن اجرای مهمان از بین خواهند رفت، اما محتویات تصویر لحظه‌ای همچنان باقی می‌مانند و یک دامنه جدید با همان نام و UUID می‌تواند با استفاده از snapshot-create متاداده‌های تصویر لحظه‌ای را بازیابی کند. به همین ترتیب، متاداده‌های هرگونه نقطه بررسی (checkpoint) از بین خواهند رفت، اما با checkpoint-create قابل بازیابی هستند.

اگر --graceful مشخص شده باشد، در صورتی که مهمان پس از یک مهلت زمانی معقول متوقف نشود، به اقدامات شدید (مانند SIGKILL) متوسل نشوید؛ در عوض یک خطا بازگردانید.

اگر --remove-logs مشخص شده باشد، فایل‌های گزارش مربوط به هر domain را حذف کنید. از همه پیکربندی‌های استقرار پشتیبانی نمی‌شود.

در مورد QEMU این پرچم تنها در صورتی پشتیبانی می‌شود که از virlogd برای مدیریت خروجی فرایند QEMU استفاده شود. در غیر این صورت این پرچم نادیده گرفته می‌شود..SS domblkerror

ساختار:

domblkerror domain

نمایش خطاهای روی دستگاه‌های بلوکی. این دستور معمولاً زمانی مفید واقع می‌شود که دستور domstate اعلام کند یک دامنه به دلیل خطای I/O متوقف (pause) شده است. دستور domblkerror تمامی دستگاه‌های بلوکی دارای وضعیت خطا و خطای رخ‌داده در هر یک از آن‌ها را فهرست می‌کند.

domblkinfo

ساختار:

domblkinfo domain [block-device --all] [--human]

دریافت اطلاعات اندازهٔ دستگاه بلوکی برای یک دامنه. یک block-device با یک نام هدفِ یکتا (<target dev='name'/>) یا فایل منبع (<source file='name'/>) برای یکی از دیسک‌های متصل به domain مطابقت دارد (برای دیدن فهرستی از این نام‌ها، همچنین domblklist را ببینید). اگر --human مشخص شده باشد، خروجی در قالبی خوانا برای انسان ارائه می‌شود. اگر --all مشخص شده باشد، خروجی جدولی خواهد بود که اطلاعات اندازهٔ تمامی دستگاه‌های بلوکی مرتبط با domain را نشان می‌دهد. گزینهٔ --all نسبت به سایر گزینه‌ها اولویت دارد.

domblklist

ساختار:

domblklist domain [--inactive] [--details]

چاپ جدولی شامل اطلاعات مختصر تمامی دستگاه‌های بلوکی مرتبط با domain. اگر --inactive مشخص شود، دستگاه‌های بلوکی که در راه‌اندازی بعدی به کار خواهند رفت استعلام می‌شوند، به جای مواردی که هم‌اکنون توسط یک دامنهٔ در حال اجرا استفاده می‌شوند. اگر --details مشخص شود، نوع دیسک و مقدار دستگاه نیز چاپ خواهند شد. سایر زمینه‌هایی که به نام دستگاه بلوکی نیاز دارند (مانند domblkinfo یا snapshot-create برای اسنپ‌شات‌های دیسک) هر یک از نام‌های هدف یا نام‌های منبع یکتای چاپ‌شده توسط این دستور را خواهند پذیرفت.

domblkstat

ساختار:

domblkstat domain [block-device] [--human]

دریافت آمار دستگاه بلوکی برای یک دامنهٔ در حال اجرا. یک block-device با یک نام هدف یکتا (<target dev='name'/>) یا فایل منبع (<source file='name'/>) برای یکی از دستگاه‌های دیسک متصل به domain مطابقت دارد (برای دیدن فهرستی از این نام‌ها، همچنین domblklist را ببینید). در دامنه‌های LXC یا QEMU، نادیده گرفتن block-device، آمار دستگاه‌های بلوکی را به‌صورت خلاصه‌وار برای کل دامنه برمی‌گرداند.

برای داشتن خروجی خواناتر برای انسان از --human استفاده کنید.

در دسترس بودن این فیلدها به هایپروایزر بستگی دارد. فیلدهای پشتیبانی‌نشده در خروجی نمایش داده نمی‌شوند. در صورت ارتباط با نسخهٔ جدیدتری از libvirtd ممکن است فیلدهای دیگری نیز ظاهر شوند.

توضیح فیلدها (فیلدها به ترتیب زیر ظاهر می‌شوند):

domblkthreshold domain dev threshold

domcontrol

سینتکس:

domcontrol domain

وضعیت رابط متصل به VMM را که برای کنترل یک دامنه استفاده می‌شود، برمی‌گرداند. برای وضعیت‌هایی غیر از "ok" یا "error"، این دستور همچنین تعداد ثانیه‌های سپری‌شده از زمان ورود رابط کنترلی به وضعیت فعلی‌اش را چاپ می‌کند.

domdirtyrate-calc

سینتکس:

domdirtyrate-calc <domain> [--seconds <sec>]
   --mode=[page-sampling | dirty-bitmap | dirty-ring]

محاسبه نرخ کثیف شدن حافظه (dirty rate) یک دامنه فعال که ممکن است توسط کاربر به منظور تصمیم‌گیری درباره مناسب بودن یا نبودن آن برای مهاجرت مورد انتظار باشد. پارامتر seconds می‌تواند برای محاسبه نرخ داده‌های تغییریافته (dirty rate) در یک بازه زمانی مشخص به کار رود که در حال حاضر حداکثر 60s را مجاز دانسته و در صورت عدم تعیین، پیش‌فرض آن 1s خواهد بود. این سه حالت page-sampling, dirty-bitmap, dirty-ring هنگام تعیین حالت محاسبه، مانعة‌الجمع و گزینه‌های جایگزین یکدیگر هستند؛ در صورت عدم تعیین، page-sampling حالت پیش‌فرض است. اطلاعات نرخ تغییرات حافظه محاسبه‌شده با فراخوانی 'domstats --dirtyrate' در دسترس است.

domdisplay

سینتکس:

domdisplay domain [--include-password] [[--type] type] [--all]

یک URI در خروجی تولید می‌کند که می‌تواند برای اتصال به نمایشگر گرافیکی دامنه از طریق VNC، SPICE یا RDP استفاده شود. نوع خاص نمایشگر گرافیکی را می‌توان با استفاده از پارامتر type انتخاب کرد (مانند "vnc"، "spice"، "rdp"). اگر --include-password مشخص شده باشد، گذرواژه کانال SPICE در URI گنجانده خواهد شد. اگر --all مشخص شود، تمام نمایشگرهای گرافیکی ممکن را نشان می‌دهد، چرا که یک ماشین مجازی می‌تواند بیش از یک نمایشگر گرافیکی داشته باشد.

domdisplay-reload

سینتکس:

domdisplay-reload <domain> [--type <type>]

بازآوری (reload) نمایشگر گرافیکی دامنه. این دستور گواهی‌های TLS آن را بدون راه‌اندازی مجدد دامنه بازآوری می‌کند. type می‌تواند هر مقداری از ثوابت نوع شمارشی virDomainGraphicsReloadType باشد. به‌طور پیش‌فرض هر نوعِ پشتیبانی‌شده‌ای بازآوری می‌شود (تاکنون فقط VNC)..SS domfsfreeze

نحو:

domfsfreeze domain [[--mountpoint] mountpoint...]

سیستم‌فایل‌های سوارشده در یک دامنهٔ در حال اجرا را برای آماده‌سازی اسنپ‌شات‌های سازگار منجمد (freeze) می‌کند.

گزینهٔ --mountpoint پارامتری به نام mountpoint می‌پذیرد که مسیر نقطهٔ اتصال سیستم‌فایل مورد نظر برای انجماد است. این گزینه می‌تواند چندین بار تکرار شود. در صورت عدم تعیین این گزینه، تمام سیستم‌فایل‌های سوارشده منجمد خواهند شد.

نکته: دستور snapshot-create دارای گزینهٔ --quiesce جهت انجماد و رفع انجماد (thaw) خودکار سیستم‌فایل‌ها است تا سازگاری اسنپ‌شات‌ها حفظ شود. دستور domfsfreeze تنها زمانی لازم است که کاربر بخواهد از قابلیت‌های اسنپ‌شات بومی دستگاه‌های ذخیره‌سازی که توسط libvirt پشتیبانی نمی‌شوند، استفاده کند.

domfsinfo

نحو:

domfsinfo domain

فهرستی از سیستم‌فایل‌های سوارشده در دامنهٔ در حال اجرا را نمایش می‌دهد. این فهرست شامل نقاط اتصال، نام دستگاه‌های سوارشده در ماشین مهمان، نوع سیستم‌فایل‌ها و نام‌های یکتای هدف استفاده‌شده در XML دامنه (<target dev='name'/>) است.

توجه داشته باشید که این دستور نیازمند یک guest agent پیکربندی‌شده و در حال اجرا در سیستم‌عامل مهمانِ دامنه است.

domfsthaw

نحو:

domfsthaw domain [[--mountpoint] mountpoint...]

سیستم‌فایل‌های سوارشده در یک دامنهٔ در حال اجرا را که توسط دستور domfsfreeze منجمد شده‌اند، از حالت انجماد خارج می‌کند (thaw).

گزینهٔ --mountpoint پارامتری به نام mountpoint می‌پذیرد که مسیر نقطهٔ اتصال سیستم‌فایل مورد نظر برای رفع انجماد است. این گزینه می‌تواند چندین بار تکرار شود. در صورت عدم تعیین این گزینه، تمام سیستم‌فایل‌های سوارشده از انجماد خارج خواهند شد.

domfstrim

نحو:

domfstrim domain [--minimum bytes] [--mountpoint mountPoint]

دستور fstrim را روی تمام سیستم‌فایل‌های سوارشده در یک دامنهٔ در حال اجرا صادر می‌کند. این عمل بلوک‌هایی را که دیگر توسط سیستم‌فایل استفاده نمی‌شوند، دور می‌ریزد (discard). اگر مقدار --minimum bytes تعیین شود، طول بازهٔ آزادِ پیوسته را به کرنل مهمان اعلام می‌کند. محدوده‌های کوچک‌تر از این مقدار ممکن است نادیده گرفته شوند (این یک پیشنهاد است و ممکن است سیستم مهمان آن را رعایت نکند). با افزایش این مقدار، عملیات fstrim برای سیستم‌فایل‌هایی با فضای آزاد بسیار پراکنده (fragmented) سریع‌تر پایان می‌یابد، اگرچه ممکن است همهٔ بلوک‌ها دور ریخته نشوند. مقدار پیش‌فرض صفر است، به معنی "دور انداختن هر بلوک آزاد". علاوه بر این، چنانچه کاربر بخواهد تنها یک نقطهٔ اتصال را trim کند، می‌توان آن را با پارامتر اختیاری --mountpoint مشخص نمود..SS domhostname

سینتکس:

domhostname domain [--source lease|agent]

نام میزبان (hostname) یک دامنه را، در صورتی که هایپروایزر آن را در دسترس قرار دهد، برمی‌گرداند.

آرگومان --source مشخص می‌کند چه منبع داده‌ای برای نام‌های میزبان استفاده شود؛ در حال حاضر 'lease' برای خواندن اجاره‌های DHCP یا 'agent' برای پرس‌وجو از سیستم‌عامل مهمان از طریق یک عامل (agent). اگر مشخص نشود، درایور روش پیش‌فرضِ دردسترس را برمی‌گرداند (برخی درایورها تنها از یک نوع منبع پشتیبانی می‌کنند).

domid

سینتکس:

domid domain-name-or-uuid

تبدیل یک نام دامنه (یا UUID) به یک شناسه دامنه (domain id).

domif-getlink

سینتکس:

domif-getlink domain interface-device [--config]

پرس‌وجوی وضعیت پیوند (link state) رابط مجازی دامنه. اگر --config مشخص شده باشد، پیکربندی ماندگار را پرس‌وجو می‌کند؛ برای اهداف سازگاری، --persistent نام مستعاری برای --config است.

interface-device می‌تواند نام مقصد رابط یا آدرس MAC آن باشد.

domif-setlink

سینتکس:

domif-setlink domain interface-device state [--config] [--print-xml]

تغییر وضعیت پیوند رابط مجازی دامنه. مقادیر ممکن برای state عبارت‌اند از "up" و "down". اگر --config مشخص شده باشد، تنها پیکربندی ماندگار دامنه تغییر می‌یابد؛ برای اهداف سازگاری، --persistent نام مستعاری برای --config است. interface-device می‌تواند نام مقصد رابط یا آدرس MAC آن باشد.

اگر --print-xml مشخص شده باشد، به جای آن XML استفاده‌شده برای به‌روزرسانی رابط چاپ می‌شود.

domifaddr

سینتکس:

domifaddr domain [interface] [--full]
   [--source lease|agent|arp]

دریافت فهرستی از رابط‌های یک دامنهٔ در حال اجرا به همراه آدرس‌های IP و MAC آن‌ها، یا خروجی محدود فقط برای یک رابط در صورتی که interface مشخص شده باشد. توجه داشته باشید که interface می‌تواند وابسته به درایور باشد؛ این نام می‌تواند نام درون سیستم‌عامل مهمان یا نامی باشد که در XML دامنه مشاهده می‌کنید. علاوه بر این، ممکن است در برخی هایپروایزرها، به‌ویژه QEMU، کل دستور نیازمند پیکربندی یک عامل مهمان (guest agent) برای دامنهٔ موردپرسش باشد.

اگر --full مشخص شده باشد، هنگامی که رابط دارای چندین آدرس IP یا نام مستعار است، نام رابط و آدرس MAC همواره نمایش داده می‌شود؛ در غیر این صورت، نام رابط و آدرس MAC تنها برای اولین نام و آدرس MAC نمایش داده می‌شود و برای سایر مواردی که از همان نام و آدرس MAC استفاده می‌کنند مقدار "-" نشان داده می‌شود.

آرگومان --source مشخص می‌کند چه منبع داده‌ای برای آدرس‌ها استفاده شود؛ در حال حاضر 'lease' برای خواندن اجاره‌های DHCP، ‏'agent' برای پرس‌وجو از سیستم‌عامل مهمان از طریق یک عامل، یا 'arp' برای دریافت IP از جدول‌های arp میزبان است. در صورت مشخص نشدن، 'lease' پیش‌فرض است..SS backup-begin

نحو:

backup-begin domain [backupxml] [checkpointxml] [--reuse-external]
    [--preserve-domain-on-shutdown]

یک عملیات پشتیبان‌گیری جدید را آغاز می‌کند. اگر backupxml مشخص نشود، پیش‌فرض یک پشتیبان‌گیری کامل با استفاده از مدل push روی نام‌فایل‌های تولیدشده توسط libvirt خواهد بود؛ ارائه XML امکان تنظیمات دقیق‌تری مانند درخواست پشتیبان‌گیری افزایشی نسبت به یک چک‌پوینت پیشین، کنترل دیسک‌های درگیر یا نام‌فایل‌های مرتبط، یا درخواست استفاده از مدل پشتیبان‌گیری pull را فراهم می‌کند. دستور backup-dumpxml مقادیر حاصل از تخصیص توسط libvirt را نمایش می‌دهد. برای اطلاعات بیشتر درباره XML پشتیبان‌گیری، ببینید: https://libvirt.org/formatbackup.html

اگر --reuse-external استفاده شود، به libvirt دستور می‌دهد تا فایل‌های موقت و خروجی ارائه‌شده توسط کاربر در backupxml را دوباره استفاده کند.

هنگامی که پرچم --preserve-domain-on-shutdown استفاده شود، چنانچه سیستم‌عامل مهمان در حین اجرای پشتیبان‌گیری خاموش شود، libvirt ماشین مجازی را متوقف (terminate) نخواهد کرد. در عوض، ماشین مجازی تا زمان اتمام عملیات پشتیبان‌گیری در وضعیت VIR_DOMAIN_PAUSED نگه داشته می‌شود. ماشین مجازی همچنین می‌تواند برای بوت دوباره، از سر گرفته (resume) شود.

اگر checkpointxml مشخص شده باشد، فایل دومی با عنصر ریشه domaincheckpoint برای ایجاد یک چک‌پوینت هم‌زمان استفاده می‌شود تا بعداً بتوان یک پشتیبان‌گیری افزایشی نسبت به زمان ایجاد این پشتیبان تهیه کرد. برای جزئیات بیشتر درباره چک‌پوینت‌ها، checkpoint-create را ببینید.

این دستور بلافاصله بازمی‌گردد و عملیات پشتیبان‌گیری در پس‌زمینه اجرا می‌شود؛ پیشرفت پشتیبان‌گیری در مدل push را می‌توان با domjobinfo یا با منتظر ماندن برای یک رویداد با event بررسی کرد (پیشرفت پشتیبان‌گیری در مدل pull تحت کنترل سرویس شخص ثالثی است که به export پروتکل NBD متصل می‌شود). این عملیات با domjobabort پایان می‌یابد.

backup-dumpxml

نحو:

backup-dumpxml [--xpath EXPRESSION] [--wrap] domain

خروجی دادن XML توصیف‌کننده عملیات پشتیبان‌گیری فعلی.

اگر آرگومان --xpath یک عبارت XPath ارائه دهد، بر روی خروجی XML ارزیابی شده و تنها گره‌های منطبق چاپ خواهند شد. رفتار پیش‌فرض این است که هر گره منطبق به عنوان یک سند مستقل چاپ شود، با این حال، برای سهولت در پردازش‌های بیشتر، آرگومان --wrap باعث می‌شود گره‌های منطبق درون یک گره ریشه مشترک قرار گیرند.

domiflist

نحو:

domiflist domain [--inactive]

چاپ جدولی که اطلاعات مختصری از تمام رابط‌های مجازی مرتبط با domain را نمایش می‌دهد. اگر --inactive مشخص شده باشد، رابط‌های مجازی که در بوت بعدی استفاده خواهند شد بررسی می‌شوند، نه آن‌هایی که در حال حاضر توسط یک دامنه در حال اجرا استفاده می‌شوند. سایر دستوراتی که به آدرس MAC رابط مجازی نیاز دارند (مانند detach-interface یا domif-setlink)، آدرس MAC چاپ‌شده توسط این دستور را خواهند پذیرفت.

domifstat

نحو:

domifstat domain interface-device

دریافت آمار رابط شبکه برای یک دامنه در حال اجرا. آمار رابط شبکه تنها برای رابط‌هایی در دسترس است که یک رابط مبدأ فیزیکی داشته باشند. این شامل مواردی چون نوع رابط 'user' نمی‌شود، زیرا یک LAN مجازی با NAT به دنیای خارج است. interface-device می‌تواند نام هدف رابط یا آدرس MAC آن باشد. لطفاً توجه داشته باشید، برای نوع مدیریت‌نشده ethernet ممکن است در آمار بازگردانده‌شده جای RX/TX معکوس باشد..SS domiftune

ساختار:

domiftune domain interface-device [[--config] [--live] | [--current]]
   [*--inbound average,peak,burst,floor*]
   [*--outbound average,peak,burst*]

تنظیم یا پرس‌وجوی پارامترهای پهنای باند رابط شبکهٔ دامنه (domain). interface-device می‌تواند نام هدف رابط (<target dev='name'/>) یا نشانی MAC باشد.

اگر هیچ‌یک از --inbound یا --outbound مشخص نشده باشد، این دستور تنظیمات پهنای باند را پرس‌وجو کرده و نمایش می‌دهد. در غیر این صورت، پهنای باند ورودی یا خروجی را تنظیم می‌کند. مقادیر average,peak,burst,floor مشابه دستور attach-interface است. مقادیر برای average، peak و floor بر حسب کیبی‌بایت بر ثانیه (kiB) بیان می‌شوند، در حالی که burst بر حسب kiB در یک فوران (burst) منفرد با سرعت peak بیان می‌شود، همان‌طور که در مستندات Network XML در https://libvirt.org/formatnetwork.html#quality-of-service شرح داده شده است.

برای پاک کردن تنظیمات ورودی یا خروجی، به‌ترتیب از --inbound یا --outbound با مقدار میانگین (average) صفر استفاده کنید.

اگر --live مشخص شود، روی یک مهمان در حال اجرا اعمال می‌شود. اگر --config مشخص شود، بر راه‌اندازی بعدی یک مهمان پایدار تأثیر می‌گذارد. اگر --current مشخص شود، بسته به وضعیت کنونی مهمان، معادل --live یا --config خواهد بود. هر دو پرچم --live و --config را می‌توان هم‌زمان داد، اما --current مانعة‌الجمع (انحصاری) است. اگر هیچ پرچمی تعیین نشود، رفتار بسته به هایپروایزر متفاوت خواهد بود.

domifannounce

ساختار

domifannounce domain [interface-device] [parameters]

درخواست از یک دامنه برای تزریق پاسخ‌های ARP از نوع "gratuitous" (بی‌درخواست) به جریان داده‌های خروجی یک رابط شبکهٔ مشخص از دامنه (یا اگر هیچ interface-device داده نشده باشد، تزریق پاسخ‌های ARP به جریان داده‌های خروجی تمام رابط‌های شبکهٔ دامنه). این کار می‌تواند برای همگام‌سازی مجدد سوییچ‌های شبکه در دامنهٔ انتشار (broadcast domain) رابط‌های یادشده هنگام تغییر توپولوژی شبکه مفید باشد. این عمل معمولاً هنگام راه‌اندازی یک دامنه یا پس از مهاجرت (migration) آن به‌طور خودکار انجام می‌شود (برای نمونه، این رفتار پیش‌فرض QEMU است)، اما یک پیکربندی پیچیده‌تر که در آن توپولوژی در اطراف یک دامنهٔ از قبل فعال تغییر می‌کند (یا احتمالاً در زمان اعلان خودکار، هنوز تمام اتصالات برقرار نشده‌اند و ترافیک عبور نمی‌کند) ممکن است از اعلانی که به‌صورت دستی راه‌اندازی می‌شود بهره ببرد.

پارامترهای اختیاری عبارتند از:

dominfo domain

domjobabort

نحو:

domjobabort domain [--postcopy]

کار (job) در حال اجرای domain را لغو می‌کند.

هنگامی که کار مورد نظر برای لغو، یک مهاجرت باشد که وارد حالت post-copy شده است، نمی‌توان آن را لغو کرد زیرا هیچ‌یک از میزبان‌های درگیر در مهاجرت وضعیت کاملی از domain را در اختیار ندارند. گزینه اختیاری --postcopy می‌تواند برای متوقف کردن چنین مهاجرتی استفاده شود، اگرچه انجام این کار ممکن است domain را عملاً تا زمانی که مهاجرت از سر گرفته شود به حالت تعلیق درآورد (همچنین گزینه --postcopy-resume از دستور migrate را ببینید).

domjobinfo

نحو:

domjobinfo domain [--completed [--keep-completed]] [--anystats] [--rawstats]

اطلاعاتی درباره کارهای در حال اجرا روی یک domain بازمی‌گرداند. گزینه --completed به virsh می‌گوید که اطلاعات مربوط به یک کار اخیراً پایان‌یافته را بازگرداند. آمار یک کار تکمیل‌شده به محض خوانده شدن (مگر اینکه از --keep-completed استفاده شود) یا هنگام راه‌اندازی مجدد libvirtd به طور خودکار پاک می‌شود.

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

در صورتی که از --rawstats استفاده شود، تمام فیلدها دقیقاً همان‌گونه که از سرور دریافت شده‌اند و بدون هیچ تلاشی برای تفسیر داده‌ها چاپ می‌شوند. فیلد "Job type:" ویژه است، زیرا توسط API گزارش می‌شود و بخشی از stats نیست.

توجه داشته باشید اطلاعات زمانی بازگردانده شده برای مهاجرت‌های تکمیل‌شده ممکن است کاملاً نامعتبر باشد، مگر اینکه زمان هر دو میزبان مبدا و مقصد همگام‌سازی شده باشد (یعنی دیمن NTP روی هر دوی آن‌ها در حال اجرا باشد).

domlaunchsecinfo

نحو:

domlaunchsecinfo domain

اطلاعاتی درباره پارامترهای امنیت راه‌اندازی (launch security) مرتبط با یک domain در حال اجرا بازمی‌گرداند.

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

domsetlaunchsecstate

نحو:

domsetlaunchsecstate domain --secrethdr hdr-filename
    --secret secret-filename [--set-address address]

یک راز امنیت راه‌اندازی (launch security secret) را در حافظه مهمان (guest) تنظیم می‌کند. مهمان باید نوع launchSecurity را در پیکربندی خود فعال کرده باشد و در حالت paused باشد. در صورت موفقیت، مهمان می‌تواند به حالت در حال اجرا (running) منتقل شود. در صورت شکست، مهمان باید نابود (destroy) شود.

گزینه --secrethdr نام فایلی را مشخص می‌کند که شامل سرآیند راز کدگذاری‌شده با base64 است. این سرآیند شامل داده‌های مورد نیاز سفت‌افزار (firmware) هایپروایزر برای بازیابی متن آشکار راز راه‌اندازی است. گزینه --secret نام فایلی را مشخص می‌کند که حاوی راز راه‌اندازی رمزگذاری‌شده با کدگذاری base64 است.

گزینه --set-address می‌تواند برای مشخص کردن یک آدرس فیزیکی درون حافظه مهمان جهت تنظیم راز استفاده شود. در صورت مشخص نشدن، آدرس توسط هایپروایزر تعیین خواهد شد..SS dommemstat

نحو:

dommemstat domain [--period seconds] [[--config] [--live] | [--current]]

دریافت آمارهای حافظه برای یک دامنهٔ در حال اجرا.

در دسترس بودن این فیلدها به هایپروایزر بستگی دارد. فیلدهای پشتیبانی‌نشده در خروجی نمایش داده نمی‌شوند. در صورت ارتباط با نسخه‌های جدیدتر libvirtd، ممکن است فیلدهای دیگری نیز ظاهر شوند.

توضیح فیلدها:

برای QEMU/KVM مجهز به balloon حافظه، تنظیم گزینهٔ اختیاری --period روی مقداری بزرگ‌تر از ۰ (بر حسب ثانیه) به درایور balloon اجازه می‌دهد تا آمارهای بیشتری را برگرداند که با دستورهای بعدی dommemstat نمایش داده خواهند شد. تنظیم --period روی ۰ جمع‌آوری اطلاعات درایور balloon را متوقف می‌کند، اما آمارهای موجود در آن را پاک نخواهد کرد. نیازمند اجرای حداقل نسخهٔ 1.5 از QEMU/KVM روی میزبان است.

پرچم‌های --live، --config و --current تنها هنگام استفاده از گزینهٔ --period جهت تنظیم دورهٔ جمع‌آوری برای درایور balloon معتبر هستند. اگر --live مشخص شود، تنها دورهٔ جمع‌آوری مهمانِ در حال اجرا تحت تأثیر قرار می‌گیرد. اگر --config مشخص شود، بر راه‌اندازی بعدی یک مهمان ماندگار (persistent) تأثیر می‌گذارد. اگر --current مشخص شود، بسته به وضعیت فعلی مهمان، معادل --live یا --config خواهد بود.

می‌توان هر دو پرچم --live و --config را هم‌زمان ارائه داد، اما --current مانعة‌الجمع (انحصاری) است. در صورتی که هیچ پرچمی مشخص نشود، رفتار بسته به وضعیت مهمان متفاوت خواهد بود.

domname

نحو:

domname domain-id-or-uuid

تبدیل شناسهٔ دامنه (یا UUID) به نام دامنه.SS dompmsuspend

نحو:

dompmsuspend domain target [--duration]

تعلیق یک دامنه در حال اجرا به یکی از این وضعیت‌ها (مقادیر ممکن برای target):

آرگومان --duration تعداد ثانیه‌هایی را مشخص می‌کند که دامنه پس از تعلیق، بیدار می‌شود (همچنین dompmwakeup را ببینید). مقدار پیش‌فرض 0 برای زمان تعلیق نامحدود است. (این ویژگی در حال حاضر توسط هیچ درایور هایپروایزری پشتیبانی نمی‌شود و باید از 0 استفاده شود).

توجه داشته باشید که این دستور نیازمند یک guest agent پیکربندی‌شده و در حال اجرا در سیستم‌عامل مهمان (guest OS) دامنه است.

توجه داشته باشید که دست‌کم برای QEMU، هنگامی که از هدف disk استفاده می‌شود، فرآیند دامنه خاتمه می‌یابد و زمانی که از libvirt درخواست بیدار کردن دامنه شود، فرآیند جدیدی راه‌اندازی خواهد شد. در نتیجه این امر، هرگونه تغییر در زمان اجرا، مانند اتصال گرم دستگاه (device hotplug) یا تنظیمات حافظه از بین می‌روند، مگر اینکه چنین تغییراتی با پرچم --config اعمال شده باشند.

dompmwakeup

نحو:

dompmwakeup domain

بیدار کردن یک دامنه از وضعیت pmsuspended (خواه توسط dompmsuspend معلق شده باشد یا از درون خود مهمان). به‌جای انتظار برای سپری شدن مدت‌زمان درخواست‌شده قبلی (در صورت وجود)، رویداد بیدارباش را به مهمانی که در وضعیت pmsuspended است تزریق می‌کند. در صورتی که دامنه در حال اجرا باشد، این عملیات لزوماً با شکست مواجه نمی‌شود.

domrename

نحو:

domrename domain new-name

تغییر نام یک دامنه. این دستور نام فعلی دامنه را به نام جدید مشخص‌شده در آرگومان دوم تغییر می‌دهد.

توجه: دامنه باید غیرفعال باشد.

domstate

نحو:

domstate domain [--reason]

وضعیت یک دامنه را بازمی‌گرداند. گزینه --reason به virsh می‌گوید که دلیل وضعیت را نیز چاپ کند..SS domstats

ساختار دستور:

domstats [--raw] [--enforce] [--backing] [--nowait] [--state]
   [--cpu-total] [--balloon] [--vcpu] [--interface]
   [--block] [--perf] [--iothread] [--memory] [--dirtyrate] [--vm]
   [[--list-active] [--list-inactive]
    [--list-persistent] [--list-transient] [--list-running]y
    [--list-paused] [--list-shutoff] [--list-other]] | [domain ...]

دریافت آمار برای چندین یا همهٔ دامنه‌ها. بدون هیچ آرگومانی، این دستور تمام آمارهای موجود را برای همهٔ دامنه‌ها چاپ می‌کند.

فهرست دامنه‌هایی که آمار آن‌ها گردآوری می‌شود را می‌توان یا با ذکر دامنه‌ها به‌صورت فهرستی جداشده با فاصله، یا با تعیین یکی از پرچم‌های پالایشی --list-NNN محدود کرد. (این دو روش را نمی‌توان ترکیب کرد.)

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

گروه‌های آماری مجزا از طریق پرچم‌های خاص قابل انتخاب هستند. به‌طور پیش‌فرض همهٔ گروه‌های آماری پشتیبانی‌شده بازگردانده می‌شوند. پرچم‌های گروه‌های آماری پشتیبانی‌شده عبارتند از: --state، --cpu-total، --balloon، --vcpu، --interface، --block، --perf، --iothread، --memory، --dirtyrate، --vm.

توجه داشته باشید که - بسته به نوع و نسخهٔ هایپروایزر یا وضعیت دامنه - ممکن است همهٔ آمارهای زیر بازگردانده نشوند.

هنگام انتخاب گروه --state فیلدهای زیر بازگردانده می‌شوند:

--cpu-total موارد زیر را بازمی‌گرداند:

--balloon موارد زیر را بازمی‌گرداند:

--vcpu موارد زیر را بازمی‌گرداند:

این گروه از آمارها همچنین آمارهای تکمیلی بر پایهٔ هر vCPU نشأت‌گرفته از هایپروایزر را گزارش می‌دهد. آمارهای مختص هایپروایزر در این گروه از الگوی نام‌گذاری زیر پیروی می‌کنند:

--interface موارد زیر را بازمی‌گرداند:

گزینهٔ --perf آمار تمام رویدادهای perf فعال‌شده را بازمی‌گرداند:

برای جزئیات بیشتر دربارهٔ هر رویداد، دستور perf را ببینید.

گزینهٔ --block اطلاعات دیسک‌های مرتبط با هر دامنه را بازمی‌گرداند. استفاده از پرچم --backing این اطلاعات را گسترش می‌دهد تا تمام منابع موجود در زنجیرهٔ پشتیبان (backing chain) را پوشش دهد، به جای حالت پیش‌فرض که اطلاعات را به لایهٔ فعال هر دیسک مهمان محدود می‌کند. اطلاعات فهرست‌شده عبارتند از:

گزینه --iothread در صورت پشتیبانی توسط hypervisor، اطلاعاتی را درباره IOThreads در مهمان در حال اجرا برمی‌گرداند.

مقدار "poll-max-ns" برای هر رشته، بیشینه نانوثانیه‌های مجاز برای رخ دادن هر بازه polling است. بازه polling دوره‌ای زمانی است که به یک رشته داده می‌شود تا پیش از پس دادن سهم پردازنده (CPU quantum) مهمان به میزبان، به پردازش داده بپردازد. مقداری که بیش از حد کوچک تنظیم شود، به IOThread اجازه نخواهد داد تا برای پردازش داده‌ها به مدت کافی روی CPU اجرا شود. مقداری که بیش از حد بزرگ تنظیم شود، زمان زیادی از CPU را به ازای هر IOThread مصرف می‌کند و مانع از اختصاص زمان به سایر رشته‌های در حال اجرا روی CPU می‌شود. بازه polling برای اهداف آماری در دسترس نیست.

گزینه --memory موارد زیر را برمی‌گرداند:

گزینه --dirtyrate موارد زیر را برمی‌گرداند:

گزینه --vm موارد زیر را برمی‌گرداند:

گزینه --vm گزارش‌گیری از آمارهای مختص hypervisor را فعال می‌کند. نام‌گذاری و مفهوم فیلدها کاملاً وابسته به hypervisor است.

آمارهای این گروه از الگوی نام‌گذاری زیر پیروی می‌کنند:

انتخاب یک گروه آماری خاص تضمین نمی‌کند که دیمن از گروه آماری انتخاب‌شده پشتیبانی کند. پرچم --enforce در صورتی که دیمن از گروه انتخاب‌شده پشتیبانی نکند، دستور را وادار به شکست می‌کند.

هنگام جمع‌آوری آمار، در صورتی که کار دیگری از قبل روی دامنه مشخص‌شده در حال اجرا باشد، ممکن است libvirtd مدتی منتظر پایان آن بماند. این امر ممکن است باعث تاخیر غیرضروری در ارائه آمار شود. استفاده از --nowait این رفتار را متوقف می‌کند. از سوی دیگر، ممکن است برخی آمارها برای چنین دامنه‌ای ناموجود باشند..SS domtime

نحو:

domtime domain { [--now] [--pretty] [--sync] [--time time] }

زمان سیستم دامنه را دریافت یا تنظیم می‌کند. در صورت اجرا بدون هیچ آرگومانی (به جز domain)، زمان فعلی سیستم دامنه چاپ می‌شود. از اصلاح‌کنندهٔ --pretty می‌توان برای چاپ زمان در قالبی خواناتر برای انسان استفاده کرد.

هنگامی که --time time مشخص شده باشد، زمان دامنه دریافت نمی‌شود بلکه تنظیم می‌گردد. اصلاح‌کنندهٔ --now مانند نام مستعاری برای --time $now عمل می‌کند، به این معنی که زمان را برابر با زمان فعلی میزبانی که virsh روی آن در حال اجرا است تنظیم می‌کند. در هر دو حالت (تنظیم و دریافت)، زمان بر حسب ثانیه نسبت به Epoch در تاریخ 1970-01-01 در UTC است. گزینهٔ --sync رفتار تنظیم را اندکی تغییر می‌دهد: زمان ارسال‌شده نادیده گرفته می‌شود، اما زمان تنظیم از RTC دامنه خوانده می‌شود. لطفاً توجه داشته باشید که برخی از هایپروایزرها ممکن است برای دریافت یا تنظیم زمان مهمان، نیازمند پیکربندی guest agent باشند.

domuuid

نحو:

domuuid domain-name-or-id

تبدیل یک نام یا شناسهٔ دامنه به UUID دامنه.

domxml-from-native

نحو:

domxml-from-native format config

تبدیل فایل config در قالب پیکربندی بومی مهمان با نام format به قالب XML دامنه. برای هایپروایزر QEMU/KVM، آرگومان format باید qemu-argv باشد. برای هایپروایزر Xen، آرگومان format می‌تواند xen-xm، xen-xl یا xen-sxpr باشد. برای هایپروایزر LXC، آرگومان format باید lxc-tools باشد. برای هایپروایزر VMware/ESX، آرگومان format باید vmware-vmx باشد. برای هایپروایزر Bhyve، آرگومان format باید bhyve-argv باشد.

domxml-to-native

نحو:

domxml-to-native format { [--xml] xml | --domain domain-name-or-id-or-uuid }

تبدیل فایل xml به قالب XML دامنه یا تبدیل یک --domain موجود به قالب پیکربندی بومی مهمان با نام format. آرگومان‌های xml و --domain مانعة‌الجمع هستند. برای اطلاع از انواع آرگومان format، به domxml-from-native مراجعه کنید.

dump

نحو:

dump domain corefilepath [--bypass-cache]
   { [--live] | [--crash] | [--reset] }
   [--verbose] [--memory-only] [--format string]

تخلیه هسته (core dump) یک دامنه در یک فایل برای تجزیه و تحلیل. اگر --live مشخص شده باشد، دامنه به جای اینکه از همان ابتدا متوقف شود، تا زمان تکمیل تخلیه به اجرای خود ادامه می‌دهد. اگر --crash مشخص شده باشد، دامنه به جای اینکه تنها در وضعیت مکث باقی بماند، با وضعیت ازکارافتاده (crashed) متوقف می‌شود. اگر --reset مشخص شده باشد، دامنه پس از تخلیهٔ موفقیت‌آمیز بازنشانی می‌شود. توجه داشته باشید که این سه سوئیچ مانعة‌الجمع هستند. اگر --bypass-cache مشخص شده باشد، ذخیره‌سازی از حافظهٔ پنهان سیستم‌فایل صرف‌نظر می‌کند، اگرچه این کار ممکن است سرعت عملیات را کاهش دهد. اگر --memory-only مشخص شده باشد، فایل خروجی یک فایل elf خواهد بود و تنها شامل حافظه دامنه و مقادیر ثبات‌های عمومی cpu می‌شود. این گزینه در صورتی که دامنه مستقیماً از دستگاه‌های میزبان استفاده کند بسیار مفید است. --format string برای تعیین قالب تخلیه 'memory-only' به کار می‌رود و string می‌تواند یکی از این موارد باشد: elf، kdump-zlib (قالب فشرده‌شده kdump با فشرده‌سازی zlib)، kdump-lzo (قالب فشرده‌شده kdump با فشرده‌سازی lzo)، kdump-snappy (قالب فشرده‌شده kdump با فشرده‌سازی snappy)، win-dmp (قالب crashdump کامل ویندوز).

پیشرفت عملیات را می‌توان با استفاده از دستور virsh به نام domjobinfo پایش کرد و با دستور domjobabort (ارسال‌شده از یک نمونهٔ دیگر virsh) لغو نمود. راهکار دیگر ارسال سیگنال SIGINT (معمولاً با Ctrl-C) به فرایند virsh در حال اجرای دستور dump است. گزینهٔ --verbose میزان پیشرفت تخلیه را نمایش می‌دهد.

نکته: برخی از هایپروایزرها ممکن است از کاربر بخواهند که مجوزهای لازم روی فایل و مسیر مشخص‌شده توسط آرگومان corefilepath را به صورت دستی بررسی و تضمین کند.

نکته: پرونده تخلیه خرابی (Crash dump) در قالب قدیمی kvmdump منسوخ شده است و از نسخه 6.1.0 به بعد نمی‌تواند توسط ابزار crash بارگذاری و پردازش شود. گزینهٔ --memory-only برای تولید فایل ELF معتبر که بعداً توسط ابزار crash قابل پردازش باشد الزامی است..SS dumpxml

نحو:

dumpxml [--inactive] [--security-info] [--update-cpu] [--migratable]
        [--xpath EXPRESSION] [--wrap] domain

اطلاعات دامنه را به صورت یک دامپ XML در خروجی استاندارد (stdout) نمایش می‌دهد؛ از این قالب می‌توان برای دستور create استفاده کرد. گزینه‌های دیگری نیز که بر دامپ XML اثر می‌گذارند می‌توانند استفاده شوند. گزینه --inactive به virsh دستور می‌دهد که بر خلاف پیکربندی فعلی دامنه، پیکربندی‌ای را استخراج کند که در راه‌اندازی بعدی دامنه استفاده خواهد شد. با استفاده از --security-info، اطلاعات حساس امنیتی نیز در خروجی XML گنجانده می‌شوند. --update-cpu نیازمندی‌های پردازنده دامنه را بر اساس پردازنده میزبان به‌روزرسانی می‌کند. با --migratable می‌توان یک XML مناسب برای مهاجرت درخواست کرد، به این معنی که با نگارش‌های قدیمی‌تر libvirt سازگار بوده و احتمالاً با گزینه‌های داخلی زمان اجرا اصلاح شده است. این گزینه ممکن است در صورت نیاز به طور خودکار گزینه‌های دیگر (--update-cpu، --security-info و ...) را فعال کند.

اگر آرگومان --xpath یک عبارت XPath ارائه دهد، آن عبارت روی XML خروجی ارزیابی می‌شود و فقط گره‌های منطبق چاپ خواهند شد. رفتار پیش‌فرض این است که هر گره منطبق به عنوان یک سند مجزا چاپ شود، اما برای سهولت پردازش‌های بیشتر، آرگومان --wrap باعث می‌شود گره‌های منطبق درون یک گره ریشه مشترک احاطه شوند.

edit

نحو:

edit domain

فایل پیکربندی XML یک دامنه را ویرایش می‌کند، که بر راه‌اندازی بعدی مهمان اثر خواهد گذاشت.

این دستور معادل است با:

virsh dumpxml --inactive --security-info domain > domain.xml
vi domain.xml (or make changes with your other text editor)
virsh define domain.xml

با این تفاوت که برخی بررسی‌های خطا را نیز انجام می‌دهد.

ویرایشگر مورد استفاده می‌تواند از طریق متغیرهای محیطی $VISUAL یا $EDITOR مشخص شود و به صورت پیش‌فرض vi است.

emulatorpin

نحو:

emulatorpin domain [cpulist] [[--live] [--config]  | [--current]]

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

برای cpulist به vcpupin مراجعه کنید.

اگر --live مشخص شده باشد، بر یک مهمان در حال اجرا اعمال می‌شود. اگر --config مشخص شده باشد، بر راه‌اندازی بعدی یک مهمان ماندگار اثر می‌گذارد. اگر --current مشخص شده باشد، بسته به وضعیت فعلی مهمان، معادل --live یا --config خواهد بود. در صورتی که cpulist ارائه شده باشد، هر دو پرچم --live و --config می‌توانند داده شوند، اما پرچم --current انحصاری و مانعة‌الجمع است. اگر هیچ پرچمی مشخص نشود، رفتار بسته به هایپروایزر متفاوت خواهد بود..SS event

نحو:

event {[domain] { event | --all } [--loop] [--timeout seconds] [--timestamp] | --list}

برای وقوع دسته‌ای از رویدادهای دامنه منتظر می‌ماند و جزئیات مناسب رویدادها را هنگام رخ دادن آن‌ها چاپ می‌کند. رویدادها را می‌توان به‌طور اختیاری بر اساس domain فیلتر کرد. استفاده از --list به‌عنوان تنها آرگومان، فهرستی از مقادیر ممکن event را که توسط این کلاینت شناخته شده است ارائه می‌دهد، اگرچه ممکن است اتصال اجازه ثبت‌نام برای همه این رویدادها را ندهد. همچنین می‌توان به جای event از --all استفاده کرد تا به‌طور هم‌زمان برای همه انواع رویداد ممکن ثبت‌نام شود.

به‌طور پیش‌فرض، این دستور یک‌باره (one-shot) است و به محض وقوع یک رویداد، وضعیت موفقیت را برمی‌گرداند؛ می‌توانید SIGINT (معمولاً از طریق Ctrl-C) را ارسال کنید تا بلافاصله خارج شوید. اگر --timeout مشخص شده باشد، دستور پس از سپری شدن seconds ثانیه از انتظار برای رویدادها دست می‌کشد. با --loop، دستور همه رویدادها را تا زمان پایان مهلت زمانی یا فشرده شدن کلید وقفه چاپ می‌کند.

هنگامی که --timestamp استفاده شود، یک برچسب زمانی خوانا برای انسان پیش از رویداد چاپ خواهد شد.

await

نحو:

await <domain> --condition <string> [--timeout seconds]

تا زمانی که --condition برای <domain> برآورده شود منتظر می‌ماند. برای به‌روزرسانی کارآمد وضعیت از رویدادها استفاده می‌کند.

شرایط پشتیبانی‌شده:

اگر --timeout مشخص شده باشد، دستور پس از سپری شدن seconds ثانیه از انتظار برای برآورده شدن شرط دست می‌کشد. اگر SIGINT به virsh تحویل داده شود (معمولاً با Ctrl-C)، انتظار بلافاصله لغو می‌شود. در حالت غیرتعاملی (non-interactive)، در هر یک از این موارد virsh به جای '1' که به معنای رخ دادن خطا است، مقدار '2' را برمی‌گرداند.

get-user-sshkeys

نحو:

get-user-sshkeys domain user

کلیدهای مجاز SSH (authorized keys) را برای user داده‌شده در domain مهمان چاپ می‌کند. لطفاً توجه داشته باشید که هر مدخل در فایل ساختاری درونی مطابق با تعریف sshd(8) دارد و virsh/libvirt با کلیدها به‌عنوان رشته‌های مات (opaque strings) رفتار می‌کند، یعنی آن‌ها را تفسیر نمی‌کند..SS guest-agent-timeout

ساختار:

guest-agent-timeout domain [--timeout value]

تعیین مدت‌زمان انتظار برای دریافت پاسخ از دستورهای guest agent. به‌طور پیش‌فرض، دستورهای عامل تا ابد در انتظار دریافت پاسخ مسدود (block) می‌شوند. value باید یک مقدار مثبت (انتظار برای تعداد ثانیه‌های مشخص) یا یکی از مقادیر زیر باشد:

در تمامی APIهای مبتنی بر guest-agent، در صورت رخداد اتمام مهلت زمانی (timeout)، چنانچه دستوری واقعی به guest agent ارسال شده باشد، کد خطای بازگردانده شده VIR_ERR_AGENT_COMMAND_TIMEOUT خواهد بود.

guestinfo

ساختار:

guestinfo domain [--user] [--os] [--timezone] [--hostname] [--filesystem]
   [--disk] [--interface] [--devices]

چاپ اطلاعات مربوط به مهمان از دیدگاه guest agent. توجه داشته باشید که این دستور مستلزم آن است که یک guest agent در سیستم‌عامل مهمان دامنه پیکربندی شده و در حال اجرا باشد.

هنگام اجرا بدون هیچ‌گونه آرگومان، این دستور تمامی انواع اطلاعاتی را که در آن لحظه توسط guest agent پشتیبانی می‌شوند چاپ کرده و از موارد غیرقابل‌دسترس صرف‌نظر می‌کند. در این حالت همیشه وضعیت موفقیت‌آمیز گزارش می‌شود.

می‌توانید با مشخص کردن یک یا چند پرچم، انواع اطلاعات بازگردانده‌شده را محدود کنید. پرچم‌های انواع اطلاعات موجود عبارتند از --user، --os، --timezone، --hostname، --filesystem، --disk، --interface، --load و --devices. اگر نوع اطلاعاتی که صراحتاً درخواست شده در آن لحظه توسط guest agent پشتیبانی نشود، فرایندها کد خروج 1 را ارائه خواهند داد.

توجه داشته باشید که بسته به نوع هایپروایزر و نگارش guest agent در حال اجرا درون دامنه، ممکن است همه اطلاعات زیر بازگردانده نشود.

هنگام انتخاب نوع اطلاعات --user، ممکن است فیلدهای زیر بازگردانده شوند:

--os بازمی‌گرداند:

--timezone بازمی‌گرداند:

--hostname بازمی‌گرداند:

--filesystem بازمی‌گرداند:

--disk بازمی‌گرداند:

--interface بازمی‌گرداند: * if.count - تعداد رابط‌های تعریف‌شده روی این domain * if.<num>.name - نام در سیستم مهمان (مانند eth0) برای رابط <num> * if.<num>.hwaddr - آدرس سخت‌افزاری در سیستم مهمان برای رابط <num> * if.<num>.addr.count - تعداد آدرس‌های IP رابط <num> * if.<num>.addr.<num1>.type - نوع آدرس IP مربوط به addr <num1> (مانند ipv4) * if.<num>.addr.<num1>.addr - آدرس IP مربوط به addr <num1> * if.<num>.addr.<num1>.prefix - پیشوند آدرس IP مربوط به addr <num1>

--load بازمی‌گرداند: * load.1m - میانگین بار پردازشی در مهمان در ۱ دقیقه گذشته * load.5m - میانگین بار پردازشی در مهمان در ۵ دقیقه گذشته * load.15m - میانگین بار پردازشی در مهمان در ۱۵ دقیقه گذشته

--devices بازمی‌گرداند: * device.count - تعداد دستگاه‌هایی که اطلاعات آن‌ها بازگردانده شده است * device.<num>.driverName - نام درایور مرتبط با دستگاه * device.<num>.driverDate - تاریخ انتشار درایور به ثانیه از مبدأ زمانی (epoch) * device.<num>.driverVersion - نگارش درایور مرتبط با دستگاه * device.<num>.idType - نوع شناسایی دستگاه (مانند pci) * device.<num>.pciVendor - شناسه سازنده (vendor ID) دستگاه PCI (به ده‌دهی) * device.<num>.pciDevice - شناسه دستگاه (device ID) دستگاه PCI (به ده‌دهی).SS guestvcpus

نحو:

guestvcpus domain [[--enable] | [--disable]] [cpulist]

پرس‌وجو یا تغییر وضعیت vCPUها از دید مهمان با استفاده از guest agent. هنگامی که بدون cpulist فراخوانی شود، اطلاعات مربوط به vCPUهای در دسترس مهمان، وضعیت آن‌ها و امکان برون‌خط شدن (offline) آن‌ها از مهمان پرس‌وجو می‌شود.

اگر cpulist ارائه شود، باید یکی از گزینه‌های --enable یا --disable نیز مشخص گردد. سپس عملیات مورد نظر روی domain اجرا می‌شود.

برای اطلاعات بیشتر دربارهٔ cpulist، vcpupin را ببینید.

iothreadadd

نحو:

iothreadadd domain iothread_id [[--config] [--live] | [--current]]

افزودن یک IOThread جدید به domain با استفاده از iothread_id مشخص‌شده. اگر iothread_id از قبل وجود داشته باشد، دستور ناموفق خواهد بود. مقدار iothread_id باید بزرگ‌تر از صفر باشد.

اگر --live مشخص شود، بر روی مهمان در حال اجرا اثر می‌گذارد. اگر مهمان در حال اجرا نباشد، خطایی بازگردانده می‌شود. اگر --config مشخص شود، بر راه‌اندازی بعدی یک مهمان ماندگار (persistent) اثر می‌گذارد. اگر --current مشخص شود، بسته به وضعیت فعلی مهمان، معادل --live یا --config خواهد بود.

iothreaddel

نحو:

iothreaddel domain iothread_id [[--config] [--live] | [--current]]

حذف یک IOThread از domain با استفاده از iothread_id مشخص‌شده. اگر یک IOThread در حال حاضر به یک منبع دیسک تخصیص یافته باشد (مانند از طریق دستور attach-disk)، تلاش برای حذف IOThread ناموفق خواهد بود. اگر iothread_id وجود نداشته باشد، خطایی رخ خواهد داد.

اگر --live مشخص شود، بر روی مهمان در حال اجرا اثر می‌گذارد. اگر مهمان در حال اجرا نباشد، خطایی بازگردانده می‌شود. اگر --config مشخص شود، بر راه‌اندازی بعدی یک مهمان ماندگار (persistent) اثر می‌گذارد. اگر --current مشخص شود، بسته به وضعیت فعلی مهمان، معادل --live یا --config خواهد بود.

iothreadinfo

نحو:

iothreadinfo domain [[--live] [--config] | [--current]]

نمایش اطلاعات پایه‌ای IOThreadهای domain شامل شناسهٔ IOThread و CPU Affinity برای هر IOThread.

اگر --live مشخص شود، داده‌های IOThreadها را از مهمان در حال اجرا دریافت می‌کند. اگر مهمان در حال اجرا نباشد، خطایی بازگردانده می‌شود. اگر --config مشخص شود، داده‌های IOThreadها را از راه‌اندازی بعدی یک مهمان ماندگار (persistent) دریافت می‌کند. اگر --current مشخص شود یا گزینه‌های --live و --config مشخص نشده باشند، داده‌های IOThread بر اساس وضعیت فعلی مهمان دریافت می‌شود که می‌تواند برخط (live) یا خاموش (offline) باشد..SS iothreadpin

نحو:

iothreadpin domain iothread cpulist [[--live] [--config] | [--current]]

سنجاق‌کردن یک IOThread دامنه به پردازنده‌های فیزیکی میزبان را تغییر می‌دهد. به منظور دریافت فهرستی از تمام IOThreadها، از iothreadinfo استفاده کنید. برای سنجاق‌کردن یک iothread، فهرست پردازنده‌های مورد نظر (cpulist) را برای شناسهٔ IOThread همان‌طور که در خروجی iothreadinfo فهرست شده است، مشخص نمایید.

مقدار cpulist فهرستی از شماره‌های پردازنده‌های فیزیکی است. نحو آن یک فهرست جداشده با کاما است و نشانه‌گذاری ویژه با استفاده از '-' و '^' (مانند '0-4'، '0-3,^2') نیز مجاز است. علامت '-' بیانگر محدوده و علامت '^' بیانگر استثنا است. اگر می‌خواهید تنظیمات iothreadpin را بازنشانی کنید، یعنی یک iothread را به همهٔ پردازنده‌های فیزیکی سنجاق کنید، کافی است مقدار 'r' را برای cpulist مشخص نمایید.

اگر --live مشخص شود، مهمان در حال اجرا تحت تأثیر قرار می‌گیرد. اگر مهمان در حال اجرا نباشد، یک خطا بازگردانده می‌شود. اگر --config مشخص شود، بر راه‌اندازی بعدی یک مهمان ماندگار اثر می‌گذارد. اگر --current مشخص شود، بسته به وضعیت فعلی مهمان، معادل --live یا --config خواهد بود. در صورت ارائهٔ cpulist، هر دو پرچم --live و --config می‌توانند داده شوند، اما --current مانعة‌الجمع است. اگر هیچ پرچمی مشخص نشده باشد، رفتار بسته به ناظر مجازی‌سازی (hypervisor) متفاوت خواهد بود.

نکته: عبارت به‌صورت ترتیبی ارزیابی می‌شود، بنابراین "0-15,^8" دقیقاً معادل "9-14,0-7,15" است اما با "^8,0-15" یکسان نیست.

iothreadset

نحو:

iothreadset domain iothread_id [[--poll-max-ns ns] [--poll-grow factor]
   [--poll-shrink divisor] [--poll-weight factor]
   [--thread-pool-min value] [--thread-pool-max value]]
   [[--config] [--live] | [--current]]

یک iothread موجود در دامنه را با استفاده از iothread_id مشخص‌شده تغییر می‌دهد. گزینهٔ --poll-max-ns بیشینه بازهٔ زمانی مجاز برای سرکشی (polling) یک IOThread را برحسب نانوثانیه تعیین می‌کند. اگر مقدار 0 (صفر) داده شود، سرکشی برای IOThread غیرفعال می‌شود. گزینهٔ --poll-grow ضریبی است که زمان سرکشی فعلی بر مبنای آن تنظیم می‌شود تا به بیشینه زمان سرکشی برسد. اگر 0 (صفر) داده شود، از ضریب پیش‌فرض استفاده خواهد شد. گزینهٔ --poll-shrink ضریب کاهشی است که زمان سرکشی فعلی بر مبنای آن کاهش می‌یابد تا به کمتر از بیشینه بازهٔ سرکشی برسد. اگر 0 (صفر) داده شود، از ضریب کاهشی پیش‌فرض استفاده خواهد شد. گزینهٔ --poll-weight مقدار جابه‌جایی وزن را برای سرکشی تطبیقی تنظیم می‌کند و تعیین می‌کند که بازهٔ رویداد اخیر چقدر بر محاسبهٔ مدت‌زمان سرکشی بعدی تأثیر بگذارد. مقادیر بزرگ‌تر وزن رویدادهای اخیر را کاهش می‌دهند. محدودهٔ معتبر [0, 63] است. در صورت عدم ذکر، مقدار تغییری نمی‌کند. مقادیر سرکشی برای یک مهمانِ در حال اجرا کاملاً پویا هستند. ذخیره‌سازی، نابودسازی، متوقف کردن و موارد مشابه در مهمان منجر به بازگشت مقادیر سرکشی به مقادیر پیش‌فرض هایپروایزر در راه‌اندازی، بازیابی و موارد بعدی خواهد شد.

گزینه‌های --thread-pool-min و --thread-pool-max به‌ترتیب کران پایین و بالای تعداد رشته‌ها در استخر کاری (worker pool) مربوط به iothread مشخص‌شده را تعیین می‌کنند. برای تغییر در یک پیکربندی غیرفعال، می‌توان -1 را برای حذف مرز مربوطه از پیکربندی دامنه مشخص کرد. برای اعمال تغییرات بر روی یک مهمان در حال اجرا، توصیه می‌شود ابتدا کران بالا (--thread-pool-max) و تنها پس از آن کران پایین (--thread-pool-min) تنظیم شود. برابر بودن کران پایین با کران بالا مجاز است، اما کران بالا نمی‌تواند مقدار صفر داشته باشد.

اگر --live مشخص شود، مهمان در حال اجرا تحت تأثیر قرار می‌گیرد. اگر مهمان در حال اجرا نباشد، خطایی بازگردانده می‌شود. اگر --current مشخص شود یا --live مشخص نشده باشد، عملیات به‌گونه‌ای انجام می‌شود که گویی --live مشخص شده است. (در اینجا منظور از "current" هر وضعیتی است که مهمان در حال حاضر دارد: زنده یا آفلاین.).SS managedsave

نحو:

managedsave domain [--bypass-cache] [{--running | --paused}] [--verbose]

یک دامنهٔ در حال اجرا را ذخیره و متوقف (stop) می‌کند، تا بتوان آن را بعداً از همان وضعیت مجدداً راه‌اندازی کرد. هنگامی که دستور start در virsh دفعهٔ بعد برای این دامنه اجرا شود، دامنه به‌طور خودکار از این وضعیت ذخیره‌شده راه‌اندازی خواهد شد. اگر --bypass-cache مشخص شده باشد، ذخیره‌سازی حافظهٔ موقت (کَش) سیستم‌فایل را دور می‌زند، هرچند ممکن است این کار سرعت عملیات را کاهش دهد.

پیشرفت کار را می‌توان با دستور virsh به نام domjobinfo پایش کرد و با دستور domjobabort (ارسال‌شده از یک نمونهٔ دیگر virsh) لغو نمود. گزینهٔ دیگر، ارسال SIGINT (معمولاً با Ctrl-C) به فرآیند virsh در حال اجرای دستور managedsave است. گزینهٔ --verbose پیشرفت ذخیره‌سازی را نمایش می‌دهد.

به‌طور معمول، راه‌اندازی یک ذخیرهٔ مدیریت‌شده (managed save) وضعیت در حال اجرا (running) یا مکث‌شده (paused) را بر اساس وضعیتی که دامنه هنگام ذخیره‌سازی داشت تعیین می‌کند؛ تعیین هر یک از پرچم‌های --running یا --paused امکان بازنویسی وضعیتی را که start باید استفاده کند فراهم می‌سازد.

دستور dominfo می‌تواند برای پرس‌وجو دربارهٔ این که آیا یک دامنه در حال حاضر ایمیج ذخیرهٔ مدیریت‌شده دارد یا خیر استفاده شود.

managedsave-define

نحو:

managedsave-define domain xml [{--running | --paused}]

فایل XML دامنه را که هنگام راه‌اندازی بعدی domain استفاده خواهد شد، به‌روزرسانی می‌کند. آرگومان xml باید نام فایلی حاوی XML جایگزین باشد، که تغییرات آن تنها در بخش‌های وابسته به میزبان از XML دامنه اِعمال شده است. برای نمونه، می‌توان از آن برای تغییر مسیر فایل‌های دیسک استفاده کرد.

ایمیج ذخیرهٔ مدیریت‌شده ثبت می‌کند که دامنه باید در وضعیت در حال اجرا یا مکث‌شده راه‌اندازی شود. به‌طور معمول، این دستور وضعیت ثبت‌شده را تغییر نمی‌دهد؛ تعیین هر یک از پرچم‌های --running یا --paused امکان بازنویسی وضعیتی را که start باید استفاده کند فراهم می‌کند.

managedsave-dumpxml

نحو:

managedsave-dumpxml [--security-info] [--xpath EXPRESSION] [--wrap] domain

فایل XML دامنه‌ای را که هنگام ایجاد فایل وضعیت ذخیره‌شده با دستور managedsave حاکم بوده است، استخراج می‌کند. استفاده از --security-info اطلاعات حساس امنیتی را نیز شامل خواهد کرد.

اگر آرگومان --xpath یک عبارت XPath را ارائه دهد، روی خروجی XML ارزیابی شده و تنها گره‌های منطبق چاپ خواهند شد. رفتار پیش‌فرض این است که هر گرهٔ منطبق به عنوان یک سند مستقل چاپ شود؛ با این حال، جهت سهولت در پردازش‌های بیشتر، آرگومان --wrap باعث می‌شود گره‌های منطبق درون یک گرهٔ ریشهٔ مشترک قرار گیرند.

managedsave-edit

نحو:

managedsave-edit domain [{--running | --paused}]

پیکربندی XML مرتبط با فایل وضعیت ذخیره‌شدهٔ یک domain را که توسط دستور managedsave ایجاد شده بود، ویرایش می‌کند.

ایمیج ذخیرهٔ مدیریت‌شده ثبت می‌کند که دامنه باید در وضعیت در حال اجرا یا مکث‌شده راه‌اندازی شود. به‌طور معمول، این دستور وضعیت ثبت‌شده را تغییر نمی‌دهد؛ تعیین هر یک از پرچم‌های --running یا --paused امکان بازنویسی وضعیتی را که restore باید استفاده کند فراهم می‌سازد.

این معادل است با:

virsh managedsave-dumpxml domain-name > state-file.xml
vi state-file.xml (or make changes with your other text editor)
virsh managedsave-define domain-name state-file-xml

با این تفاوت که برخی بررسی‌های خطا را نیز انجام می‌دهد.

ویرایشگر مورد استفاده می‌تواند از طریق متغیرهای محیطی $VISUAL یا $EDITOR مشخص شود، و پیش‌فرض آن vi است..SS managedsave-remove

نحو:

managedsave-remove domain

فایل وضعیت managedsave را برای یک دامنه، در صورت وجود، حذف می‌کند. این کار تضمین می‌کند که دامنه در دفعه بعدی راه‌اندازی، یک بوت کامل انجام خواهد داد.

maxvcpus

نحو:

maxvcpus [type]

حداکثر تعداد پردازنده‌های مجازی (vCPU) پشتیبانی‌شده برای یک ماشین مجازی مهمان را در این اتصال ارائه می‌دهد. در صورت ارائه، پارامتر type باید یک صفت type معتبر برای عنصر <domain> در XML باشد.

memtune

نحو:

memtune domain [--hard-limit size] [--soft-limit size] [--swap-hard-limit size]
   [--min-guarantee size] [[--config] [--live] | [--current]]

امکان مشاهده یا تنظیم پارامترهای حافظه دامنه را فراهم می‌کند. بدون پرچم‌ها، تنظیمات فعلی نمایش داده می‌شوند؛ با یک پرچم، در صورت پشتیبانی توسط هایپروایزر، حد مربوطه تنظیم می‌شود. فناوری‌های LXC و QEMU/KVM از --hard-limit، --soft-limit و --swap-hard-limit پشتیبانی می‌کنند. --min-guarantee تنها توسط هایپروایزر ESX پشتیبانی می‌شود. هر یک از این محدودیت‌ها اعداد صحیح مقیاس‌پذیر هستند (بخش NOTES در بالا را ببینید)، و در صورت عدم وجود پسوند، مقدار پیش‌فرض بر حسب کیبی‌بایت (بلوک‌های 1024 بایتی) خواهد بود. لایب‌ویرت (Libvirt) مقادیر را به نزدیک‌ترین کیبی‌بایت به بالا گرد می‌کند. برخی از هایپروایزرها به دانه‌بندی بزرگ‌تری نسبت به KiB نیاز دارند، و درخواست‌هایی که مضرب صحیحی از آن نباشند به بالا گرد خواهند شد. برای مثال، vSphere/ESX پارامتر را به مبی‌بایت (1024 کیبی‌بایت) به سمت بالا گرد می‌کند.

اگر --live مشخص شود، بر یک مهمان در حال اجرا تأثیر می‌گذارد. اگر --config مشخص شود، بر راه‌اندازی بعدی یک مهمان ماندگار (persistent) تأثیر می‌گذارد. اگر --current مشخص شود، بسته به وضعیت فعلی مهمان، معادل --live یا --config خواهد بود. می‌توان هر دو پرچم --live و --config را ارائه داد، اما --current مانعة‌الجمع (انحصاری) است. اگر هیچ پرچمی مشخص نشود، رفتار برنامه بسته به هایپروایزر متفاوت خواهد بود.

برای QEMU/KVM، پارامترها بر کل فرآیند QEMU اعمال می‌شوند. بنابراین، هنگام محاسبه آن‌ها، باید RAM مهمان، RAM گرافیکی مهمان و مقداری سربار حافظه خود QEMU را با هم جمع کرد. بخش آخر به سختی قابل تعیین است، بنابراین باید حدس زد و آزمایش کرد.

برای LXC، مقدار نمایش داده شده hard_limit همان تنظیم حافظه فعلی از XML یا نتایج حاصل از دستور virsh setmem است.

مشخص کردن مقدار -1 برای این محدودیت‌ها به عنوان نامحدود تفسیر می‌شود..SS metadata

Syntax:

metadata domain [[--live] [--config] | [--current]]
   [--edit] [uri] [key] [set] [--remove]

نمایش یا ویرایش متاداده‌های سفارشی XML یک دامنه. این متاداده یک XML تعریف‌شده توسط کاربر است که امکان ذخیره داده‌های دلخواه XML را در تعریف دامنه فراهم می‌کند. چندین بخش مجزای متاداده سفارشی را می‌توان در XML دامنه ذخیره کرد. این بخش‌ها توسط یک فضای نام (namespace) اختصاصی XML که از طریق آرگومان uri ارائه می‌شود، شناسایی می‌گردند. (همچنین desc را ببینید که با متاداده‌های متنی یک دامنه کار می‌کند.)

پرچم‌های --live یا --config انتخاب می‌کنند که آیا این دستور بر روی تعاریف زنده یا ماندگار دامنه کار کند. اگر هر دو گزینه --live و --config مشخص شوند، در دریافت توضیحات فعلی گزینه --config اولویت دارد و هنگام تنظیم توضیحات، هم پیکربندی زنده و هم پیکربندی ذخیره‌شده (config) به‌روزرسانی می‌شوند. گزینه --current مانعة‌الجمع است و اگر هیچ‌یک از این‌ها مشخص نشده باشد به‌طور ضمنی اعمال می‌شود.

پرچم --remove مشخص می‌کند عنصر متاداده‌ای که توسط آرگومان uri تعیین شده است، باید به‌جای به‌روزرسانی، حذف شود.

پرچم --edit مشخص می‌کند که یک ویرایشگر حاوی متاداده شناسایی‌شده توسط آرگومان uri باز شود و محتویات پس از آن ذخیره گردند. در غیر این صورت، محتوای جدید می‌تواند از طریق آرگومان set ارائه شود.

هنگام تنظیم متاداده از طریق --edit یا set، آرگومان key باید مشخص شود و برای پیشوند دادن به عناصر سفارشی جهت اتصال آن‌ها به فضای نام اختصاصی استفاده می‌شود.

اگر هیچ‌یک از گزینه‌های --edit و set مشخص نشده باشند، متاداده XML مربوط به فضای نام uri به‌جای تغییر یافتن، نمایش داده می‌شود.

migrate

Syntax:

migrate [--live] [--offline] [--direct] [--p2p [--tunnelled]]
   [--persistent] [--undefinesource] [--suspend] [--copy-storage-all]
   [--copy-storage-inc] [--change-protection] [--unsafe] [--verbose]
   [--rdma-pin-all] [--abort-on-error] [--postcopy]
   [--postcopy-after-precopy] [--postcopy-resume] [--zerocopy]
   domain desturi [migrateuri] [graphicsuri] [listen-address] [dname]
   [--timeout seconds [--timeout-suspend | --timeout-postcopy]]
   [--xml file]
   [--migrate-disks disk-list] [--migrate-disks-detect-zeroes disk-list]
   [--migrate-disks-target-zero disk-list]
   [--disks-port port]
   [--compressed] [--comp-methods method-list]
   [--comp-mt-level] [--comp-mt-threads] [--comp-mt-dthreads]
   [--comp-xbzrle-cache] [--comp-zlib-level] [--comp-zstd-level]
   [--auto-converge] [auto-converge-initial]
   [auto-converge-increment] [--persistent-xml file] [--tls]
   [--postcopy-bandwidth bandwidth]
   [--parallel [--parallel-connections connections]]
   [--bandwidth bandwidth] [--tls-destination hostname]
   [--disks-uri URI] [--copy-storage-synchronous-writes]
   [--available-switchover-bandwidth bandwidth]

مهاجرت دامنه به یک میزبان دیگر. برای مهاجرت زنده --live، برای مهاجرت همتا‌به‌همتا <--p2p>، برای مهاجرت مستقیم --direct، یا برای مهاجرت تونل‌شده --tunnelled را اضافه کنید. گزینه --offline تعریف دامنه را بدون راه‌اندازی دامنه در مقصد و بدون متوقف کردن آن در میزبان مبدأ مهاجرت می‌دهد. مهاجرت آفلاین ممکن است با دامنه‌های غیرفعال استفاده شود و باید همراه با گزینه --persistent به کار رود.

گزینه --persistent دامنه را در میزبان مقصد ماندگار باقی می‌گذارد (برای نکات خاص هنگام استفاده با --xml به بخش زیر مراجعه کنید)، --undefinesource تعریف دامنه را در میزبان مبدأ حذف (undefine) می‌کند، و --suspend دامنه را در میزبان مقصد در حالت تعلیق باقی می‌گذارد.

گزینه --copy-storage-all نشان‌دهنده مهاجرت با فضای ذخیره‌سازی غیرمشترک همراه با رونوشت کامل دیسک است، و --copy-storage-inc نشان‌دهنده مهاجرت با ذخیره‌سازی غیرمشترک به همراه رونوشت افزایشی است (ایمیج پایه یکسانی بین مبدأ و مقصد به اشتراک گذاشته شده است). در هر دو حالت، ایمیج‌های دیسک باید در میزبان مقصد وجود داشته باشند؛ گزینه‌های --copy-storage-... تنها به libvirt می‌گویند داده‌ها را از ایمیج‌های میزبان مبدأ به ایمیج‌های موجود در همان مسیر در میزبان مقصد منتقل کند. به‌طور پیش‌فرض تنها ایمیج‌های غیرمشترک و غیرفقط‌خواندنی منتقل می‌شوند. از --migrate-disks برای مشخص کردن صریح فهرستی از دیسک‌های هدف جهت انتقال از طریق آرگومان جداشده با کامای disk-list استفاده کنید. گزینه --migrate-disks-detect-zeroes که فهرستی از نام‌های دیسک هدفِ جداشده با کاما را دریافت می‌کند، تشخیص بلوک‌های صفر را برای دیسک‌های مهاجرت‌یافته فهرست‌شده فعال می‌کند. این بلوک‌ها در مقصد منتقل یا تخصیص داده نمی‌شوند (نیاز دارد که گزینه 'discard' در دیسک مربوطه روی 'unmap' تنظیم شده باشد)، که در عمل دیسک را با هزینه بار اضافه CPU، تُنُک (sparse) می‌سازد. گزینه --migrate-disks-target-zero که فهرستی از نام‌های دیسک هدفِ جداشده با کاما را دریافت می‌کند، ایمیج‌های دیسکی را مشخص می‌سازد که هدف آن‌ها پیش از مهاجرت صفر شده است و بنابراین ناظر مجازی‌سازی (hypervisor) تلاشی برای صفر کردن آن‌ها نخواهد کرد. با استفاده از پرچم --copy-storage-synchronous-writes، مهاجرت داده‌های دیسک به‌طور همگام نوشتن‌های دیسک مهمان را هم در مبدأ اصلی و هم در مقصد مدیریت می‌کند تا اطمینان حاصل شود که مهاجرت دیسک همگرا می‌شود، هرچند ممکن است به بهای کاهش کارایی انفجاری (burst performance) تمام شود.

گزینه --change-protection اعمال می‌کند که در حین انجام مهاجرت هیچ تغییر پیکربندی ناسازگاری بر روی دامنه رخ ندهد؛ این پرچم در صورت پشتیبانی توسط ناظر مجازی‌سازی به‌صورت ضمنی فعال است، اما می‌تواند به‌طور صریح برای رد کردن مهاجرت در صورتی که ناظر فاقد پشتیبانی از محافظت تغییرات باشد، استفاده شود.

گزینه --verbose پیشرفت مهاجرت را نمایش می‌دهد.

گزینه --abort-on-error در صورت وقوع یک خطای نرم/گذرا (برای مثال خطای I/O) در حین مهاجرت، عملیات را لغو می‌کند.

گزینه --postcopy منطق پس‌رونوشت (post-copy) را در مهاجرت فعال می‌کند، اما در عمل post-copy را آغاز نمی‌کند، به این معنی که مهاجرت در حالت پیش‌رونوشت (pre-copy) شروع می‌شود. پس از در حال اجرا بودن مهاجرت، کاربر می‌تواند با استفاده از دستور migrate-postcopy که از یک نمونه دیگر virsh ارسال می‌شود به حالت post-copy تغییر وضعیت دهد یا از --postcopy-after-precopy همراه با --postcopy استفاده کند تا به libvirt اجازه دهد پس از پایان اولین دور pre-copy به‌طور خودکار به post-copy تغییر وضعیت دهد. بیشینه پهنای باند مصرفی در طول فاز post-copy می‌تواند با استفاده از --postcopy-bandwidth محدود شود. بیشینه پهنای باند مصرفی در طول فاز pre-copy می‌تواند با استفاده از --bandwidth محدود شود. در صورتی که اتصال میان میزبان‌ها در حین قرار داشتن مهاجرت در حالت post-copy قطع شود، دامنه را نمی‌توان در هیچ‌یک از میزبان‌های مبدأ یا مقصد ادامه داد و دستور migrate خطایی را گزارش کرده و دامنه را در هر دو میزبان در حالت فعال باقی می‌گذارد. برای بازیابی از چنین وضعیتی، دستور اولیه migrate را با پرچم اضافی --postcopy-resume تکرار کنید.

گزینه --auto-converge همگرایی را در طول مهاجرت زنده تحمیل می‌کند. نرخ مهار اولیه CPU مهمان را می‌توان با auto-converge-initial تنظیم کرد. اگر نرخ مهار اولیه برای تضمین همگرایی کافی نباشد، این نرخ به‌صورت دوره‌ای به میزان auto-converge-increment افزایش می‌یابد.

گزینه --rdma-pin-all می‌تواند با مهاجرت RDMA (یعنی زمانی که migrateuri با rdma:// شروع می‌شود) استفاده شود تا به ناظر مجازی‌سازی بگوید تمام حافظه دامنه را یک‌باره قبل از آغاز مهاجرت پین (قفل در حافظه) کند، به جای اینکه صفحات حافظه را بر حسب نیاز پین کند. در QEMU/KVM این مستلزم آن است که عنصر تنظیم حافظه hard_limit (در XML دامنه) استفاده شود و روی حداکثر حافظه پیکربندی‌شده برای دامنه به‌علاوه هر مقدار حافظه مصرفی توسط خود فرایند QEMU تنظیم گردد. از تعیین بیش از حد بالای حد حافظه (و در نتیجه امکان قفل کردن بیشتر حافظه میزبان توسط دامنه) برحذر باشید. انجام این کار می‌تواند هم برای دامنه و هم برای خود میزبان خطرناک باشد زیرا هسته میزبان ممکن است با کمبود حافظه مواجه شود.

گزینه --zerocopy درخواست می‌کند که از سازوکار نسخه‌برداری صفر (zero-copy) برای مهاجرت صفحات حافظه استفاده شود. برای QEMU/KVM این بدان معناست که QEMU موقتاً مجاز خواهد بود تمام صفحات مهمان را در حافظه میزبان قفل کند، هرچند تنها صفحاتی که در صف انتقال قرار دارند در یک زمان قفل خواهند شد.

نکته: ناظرهای مجازی‌سازی مجزا معمولاً از تمام انواع ممکن مهاجرت پشتیبانی نمی‌کنند. برای مثال، QEMU از مهاجرت مستقیم پشتیبانی نمی‌کند.

در برخی موارد ممکن است libvirt از مهاجرت دامنه خودداری کند زیرا انجام این کار می‌تواند منجر به مشکلات بالقوه‌ای مانند خرابی داده‌ها شود، و بنابراین مهاجرت ناامن در نظر گرفته می‌شود. برای دامنه QEMU، این امر ممکن است هنگامی رخ دهد که دامنه از دیسک‌هایی بدون تنظیم صریح حالت کش بر روی "none" استفاده کند. مهاجرت چنین دامنه‌هایی ناامن است مگر اینکه ایمیج‌های دیسک بر روی یک فایل‌سیستم خوشه‌ای همگام (coherent clustered filesystem) مانند GFS2 یا GPFS ذخیره شده باشند. اگر مطمئن هستید که مهاجرت امن است یا اهمیتی برایتان ندارد، از --unsafe برای تحمیل مهاجرت استفاده کنید.

آرگومان dname برای تغییر نام دامنه به نامی جدید در طول مهاجرت استفاده می‌شود، که معمولاً می‌توان از آن نیز صرف‌نظر کرد.

گزینه --xml file، اگرچه معمولاً لازم نیست، می‌تواند برای ارائه یک فایل XML جایگزین جهت استفاده در مقصد به کار رود تا مجموعه بزرگ‌تری از تغییرات را در هر بخش مختص میزبان از XML دامنه اعمال کند، مانند در نظر گرفتن تفاوت‌های نام‌گذاری میان مبدأ و مقصد در دسترسی به فضای ذخیره‌سازی زیرین. اگر --xml همراه با --persistent استفاده شود، معمولاً لازم است تعریف ماندگار XML از طریق --persistent-xml (به زیر مراجعه کنید) ارائه شود که به همان ترتیبی که XML ارائه‌شده به --file اصلاح شده بود، تصحیح شود.

اگر --persistent فعال باشد، --persistent-xml file می‌تواند برای ارائه یک فایل XML جایگزین که به عنوان تعریف مهمان ماندگار در میزبان مقصد استفاده خواهد شد، به کار رود.

گزینه --timeout seconds به virsh می‌گوید هنگامی که مهاجرت زنده بیش از آن تعداد ثانیه طول کشید، یک اقدام مشخص‌شده را اجرا کند. این گزینه تنها همراه با --live می‌تواند به کار رود. اگر --timeout-suspend مشخص شده باشد، دامنه پس از اتمام مهلت زمانی معلق می‌شود و مهاجرت به‌صورت آفلاین کامل خواهد شد؛ این حالت پیش‌فرض است اگر هیچ گزینه --timeout-\`` در خط فرمان مشخص نشده باشد. هنگامی که *--timeout-postcopy استفاده شود، virsh در زمان پایان مهلت، مهاجرت را از pre-copy به post-copy تغییر وضعیت می‌دهد؛ برای کارکرد این قابلیت، مهاجرت باید با گزینه --postcopy آغاز شده باشد..sp گزینهٔ --compressed فشرده‌سازی را فعال می‌کند؛ روش فشرده‌سازی با --comp-methods انتخاب می‌شود. روش‌های پشتیبانی‌شده عبارتند از "mt"، "xbzrle"، "zlib" و "zstd". مجموعه روش‌های پشتیبانی‌شده و ترکیب‌های آن‌ها به هایپروایزر و گزینه‌های مهاجرت بستگی دارد. QEMU فقط در صورت استفاده از --parallel از روش‌های "zlib" و "zstd" پشتیبانی می‌کند و نمی‌توان آن‌ها را هم‌زمان به کار برد. هنگامی که هیچ روشی مشخص نشده باشد، روش‌های پیش‌فرض هایپروایزر استفاده خواهند شد. QEMU تا زمانی که --parallel استفاده نشود، به‌طور پیش‌فرض از "xbzrle" استفاده می‌کند. برای مهاجرت‌های --parallel، بستهٔ QEMU هیچ روش فشرده‌سازی پیش‌فرضی ارائه نمی‌دهد و بنابراین باید با استفاده از --comp-method به‌طور صریح مشخص شود. روش‌های فشرده‌سازی را می‌توان بیشتر تنظیم کرد. --comp-mt-level سطح فشرده‌سازی را برای روش "mt" مشخص می‌کند. مقادیر در بازهٔ ۰ تا ۹ هستند که در آن ۱ بیشترین سرعت و ۹ بیشترین فشرده‌سازی است. --comp-mt-threads و --comp-mt-dthreads به ترتیب تعداد رشته‌های فشرده‌سازی در مبدأ و تعداد رشته‌های بازگشایی در مقصد را تنظیم می‌کنند. --comp-xbzrle-cache اندازهٔ page cache را بر حسب بایت مشخص می‌کند. --comp-zlib-level سطح فشرده‌سازی را هنگام استفاده از روش "zlib" تنظیم می‌کند. مقادیر در بازهٔ ۰ تا ۹ قرار دارند و پیش‌فرض آن ۱ است، که در آن ۰ عدم فشرده‌سازی، ۱ حداکثر سرعت و ۹ بیشترین فشرده‌سازی است. --comp-zstd-level سطح فشرده‌سازی را هنگام استفاده از روش "zstd" تنظیم می‌کند. مقادیر در بازهٔ ۰ تا ۲۰ قرار دارند و پیش‌فرض آن ۱ است، که در آن ۰ بدون فشرده‌سازی، ۱ حداکثر سرعت و ۲۰ بیشترین فشرده‌سازی است.

ارائهٔ --tls باعث می‌شود که مهاجرت، برای انجام مهاجرت دامین، از پیکربندی TLS تنظیم‌شده روی میزبان استفاده کند (به migrate_tls_x509_cert_dir در /etc/libvirt/qemu.conf مراجعه کنید). استفاده از این گزینه مستلزم پیکربندی صحیح TLS هم برای مبدأ و هم برای مقصد است. در حالت معمول، برای موفقیت‌آمیز بودن اعتبارسنجی TLS، گواهی TLS میزبان مقصد باید با نام میزبان مطابقت داشته باشد. هنگامی که گواهی با hostname مقصد مطابقت ندارد و hostname مورد انتظار گواهی مشخص است، می‌توان از --tls-destination برای ارسال hostname مورد انتظار در هنگام شروع مهاجرت استفاده کرد.

گزینهٔ --parallel باعث می‌شود داده‌های مهاجرت از طریق چندین اتصال موازی ارسال شوند. تعداد این اتصالات را می‌توان با استفاده از --parallel-connections تنظیم کرد. اتصالات موازی می‌توانند به اشباع پیوند شبکه بین مبدأ و مقصد و در نتیجه افزایش سرعت مهاجرت کمک کنند.

مهاجرت در حال اجرا را می‌توان با متوقف کردن virsh (معمولاً با استفاده از Ctrl-C) یا با دستور domjobabort ارسال‌شده از نمونهٔ دیگری از virsh لغو کرد.

پارامترهای desturi و migrateuri را می‌توان برای کنترل این که مهاجرت از کدام مقصد استفاده کند به کار برد. desturi برای مهاجرت مدیریت‌شده (managed) مهم است، اما برای مهاجرت مستقیم (direct) استفاده نمی‌شود؛ migrateuri برای مهاجرت مستقیم الزامی است، اما معمولاً برای مهاجرت مدیریت‌شده می‌تواند به‌طور خودکار تعیین شود.

نکته: پارامتر desturi برای مهاجرت عادی و مهاجرت peer2peer معنای متفاوتی دارد:

در شرایط خاصی که به کنترل کامل اتصال نیاز دارید و/یا libvirt به طرف دوردست دسترسی شبکه ندارد، می‌توانید از یک انتقال‌دهندهٔ UNIX در URI استفاده کرده و یک مسیر سوکت را در پرسمان مشخص کنید؛ برای مثال با راه‌انداز qemu می‌توانید از این استفاده کنید:

qemu+unix:///system?socket=/path/to/socket

هنگامی که migrateuri مشخص نشده باشد، libvirt به‌طور خودکار URI ویژهٔ هایپروایزر را تعیین خواهد کرد. برخی از هایپروایزرها، از جمله QEMU، دارای پارامتر پیکربندی اختیاری "migration_host" هستند (زمانی که میزبان دارای چندین رابط شبکه است مفید است). اگر این مقدار مشخص نشده باشد، libvirt نام را با جستجوی hostname پیکربندی‌شدهٔ میزبان مقصد تعیین می‌کند.

چندین سناریو وجود دارد که تعیین migrateuri ممکن است در آن‌ها مفید باشد:

unix:///path/to/socket

برای جزئیات بیشتر دربارهٔ URIهای مهاجرت به https://libvirt.org/migration.html#uris مراجعه کنید.

پارامتر اختیاری graphicsuri پارامترهای اتصال استفاده‌شده برای بازاتصال خودکار کلاینت‌های گرافیکی در انتهای مهاجرت را لغو می‌کند. در صورت حذف آن، libvirt پارامترها را بر اساس آدرس IP میزبان مقصد محاسبه خواهد کرد. در صورتی که کلاینت به شبکه‌ای که میزبان‌های مجازی‌سازی به آن متصل هستند دسترسی مستقیم نداشته باشد و نیاز به اتصال از طریق یک پروکسی داشته باشد، می‌توان از graphicsuri برای تعیین نشانی‌ای که کلاینت باید به آن متصل شود استفاده کرد. ساختار URI به صورت زیر است:

protocol://hostname[:port]/[?parameters]

که در آن protocol یکی از مقادیر "spice" یا "vnc" است و parameters فهرستی از پارامترهای خاص پروتکل است که با '&' از هم جدا شده‌اند. پارامترهای شناخته‌شدهٔ کنونی "tlsPort" و "tlsSubject" هستند. به عنوان مثال،

spice://target.host.com:1234/?tlsPort=4567

پارامتر اختیاری listen-address نشانی شنودی را که هایپروایزر در سمت مقصد باید برای مهاجرت ورودی به آن متصل (bind) شود تنظیم می‌کند. هر دو آدرس IPv4 و IPv6 و همچنین نام‌های میزبان (تحلیل نام در مقصد انجام می‌شود) پذیرفته می‌شوند. برخی هایپروایزرها از تعیین نشانی شنود پشتیبانی نمی‌کنند و در صورت استفاده از این پارامتر خطایی را برمی‌گردانند. اگر desturi از روش انتقال UNIX استفاده کند، نمی‌توان از این پارامتر استفاده کرد.

پارامتر اختیاری disks-port پورتی را که هایپروایزر در سمت مقصد باید برای ترافیک ورودی دیسک‌ها به آن bind شود تنظیم می‌کند. در حال حاضر این پارامتر فقط توسط QEMU پشتیبانی می‌شود.

پارامتر اختیاری disks-uri نیز می‌تواند مشخص شود (با disks-port مانعة‌الجمع است) تا تعیین کند هایپروایزر دوردست هنگام مهاجرت دیسک‌ها باید به چه چیزی bind/connect شود. این می‌تواند tcp://address:port برای تعیین نشانی شنود (که --migrate-uri و --listen-address را برای مهاجرت دیسک لغو می‌کند) و یک پورت باشد، یا unix:///path/to/socket در صورتی که نیاز داشته باشید مهاجرت دیسک از طریق یک سوکت UNIX با آن مسیر مشخص‌شده انجام شود. در این حالت باید مطمئن شوید همان مسیر سوکت برای هر دو هایپروایزر مبدأ و مقصد در دسترس است و اتصال به سوکت در مبدأ (پس از این که هایپروایزر آن را در مقصد ایجاد کرد) واقعاً به مقصد متصل می‌شود. اگر از SELinux استفاده می‌کنید (حداقل در میزبان مبدأ)، باید اطمینان حاصل کنید که سوکت در مبدأ برای برقراری اتصال توسط libvirtd/QEMU قابل دسترسی است. Libvirt نمی‌تواند بافت (context) سوکت موجود را تغییر دهد زیرا با نمایش فایلیِ سوکت تفاوت دارد و context توسط ایجادکنندهٔ آن (معمولاً با استفاده از توابع setsockcreatecon{,_raw}()) تعیین می‌شود.

گزینهٔ اختیاری --available-switchover-bandwidth پهنای باند محاسبه‌شدهٔ خودکار (بر حسب MiB/s) در دسترس برای فاز نهایی مهاجرت (pre-copy) را لغو می‌کند؛ فازی که در طول آن پردازنده‌ها متوقف شده و تمام حافظه و وضعیت باقی‌ماندهٔ دستگاه‌ها منتقل می‌شود. دانستن این پهنای باند برای برآورد دقیق زمان از کارافتادگی (downtime) دامین و تصمیم‌گیری در مورد لحظهٔ مناسب جابه‌جایی مهم است. معمولاً این مقدار بر اساس پهنای باند استفاده‌شده توسط مهاجرت تخمین زده می‌شود، اما این مقدار ممکن است کمتر از پهنای باند در دسترس واقعی باشد. استفاده از این گزینه می‌تواند به همگرایی مهاجرت کمک کند، در شرایطی که مهاجرت با این تصور که پهنای باند کافی برای مطابقت با حداکثر زمان downtime پیکربندی‌شده وجود ندارد، مکرراً تکرار می‌شود..SS migrate-compcache

نحو:

migrate-compcache domain [--size bytes]

اندازه حافظه نهان (کش) مورد استفاده برای فشرده‌سازی صفحه‌های حافظه‌ای را که به‌طور مکرر در حین مهاجرت زنده منتقل می‌شوند (به بایت)، تنظیم و/یا دریافت می‌کند. هنگامی که بدون size فراخوانی شود، دستور صرفاً اندازه فعلی کش فشرده‌سازی را چاپ می‌کند. هنگامی که size مشخص شده باشد، از hypervisor درخواست می‌شود کش فشرده‌سازی را به size بایت تغییر دهد و سپس اندازه فعلی چاپ می‌شود (ممکن است نتیجه به دلیل گرد کردن انجام‌شده توسط hypervisor با اندازه درخواستی متفاوت باشد). گزینه size برای استفاده در حین مهاجرت زنده دامنه در نظر گرفته شده است، تا واکنشی به روند پیشرفت مهاجرت و افزایش تعداد عدم اصابت‌های کش فشرده‌سازی (compression cache misses) به‌دست‌آمده از domjobinfo باشد.

migrate-getmaxdowntime

نحو:

migrate-getmaxdowntime domain

حداکثر زمان از کار افتادگی (downtime) قابل تحمل را برای دامنه‌ای که در حال مهاجرت زنده به میزبان دیگری است دریافت می‌کند. این مقدار، تعداد میلی‌ثانیه‌هایی است که مهمان مجاز است در انتهای مهاجرت زنده غیرفعال باشد.

migrate-getspeed

نحو:

migrate-getspeed domain [--postcopy]

حداکثر پهنای باند مهاجرت (بر حسب MiB/s) را برای یک دامنه دریافت می‌کند. در صورت مشخص شدن گزینه --postcopy، این دستور حداکثر پهنای باند مجاز را در طول فاز مهاجرت post-copy دریافت خواهد کرد.

migrate-postcopy

نحو:

migrate-postcopy domain

وضعیت مهاجرت فعلی را از pre-copy به post-copy تغییر می‌دهد. این قابلیت تنها برای مهاجرتی که با گزینه --postcopy آغاز شده باشد، پشتیبانی می‌شود.

migrate-setmaxdowntime

نحو:

migrate-setmaxdowntime domain downtime

حداکثر زمان از کار افتادگی (downtime) قابل تحمل را برای دامنه‌ای که در حال مهاجرت زنده به میزبان دیگری است تنظیم می‌کند. آرگومان downtime تعداد میلی‌ثانیه‌هایی است که مهمان مجاز است در پایان مهاجرت زنده غیرفعال باشد..SS migrate-setspeed

نحو:

migrate-setspeed domain bandwidth [--postcopy]

تنظیم حداکثر پهنای باند مهاجرت (بر حسب MiB/s) برای دامنه‌ای که در حال مهاجرت به میزبان دیگری است. bandwidth به عنوان یک مقدار unsigned long long تفسیر می‌شود. مشخص کردن یک مقدار منفی منجر به ارائه مقداری اساساً نامحدود به هایپروایزر خواهد شد. هایپروایزر می‌تواند انتخاب کند که مقدار را رد کند یا آن را به حداکثر مقدار مجاز تبدیل نماید. اگر گزینه --postcopy مشخص شده باشد، دستور حداکثر پهنای باند مجاز را در طول مرحله مهاجرت پس‌رونوشت (post-copy) تنظیم می‌کند.

numatune

نحو:

numatune domain [--mode mode] [--nodeset nodeset]
   [[--config] [--live] | [--current]]

تنظیم یا دریافت پارامترهای numa دامنه، متناظر با عنصر <numatune> در XML دامنه. بدون پرچم‌ها، تنظیمات فعلی نمایش داده می‌شوند.

مقدار mode می‌تواند یکی از موارد `strict'، `interleave'، `preferred' و 'restrictive' باشد، یا در صورتی که دیمن پشتیبانی کند، هر عدد معتبری از شمارشگر virDomainNumatuneMemMode باشد. برای یک دامنه در حال اجرا، mode قابل تغییر نیست و nodeset تنها در صورتی قابل تغییر است که دامنه با حالت `restrictive' شروع به کار کرده باشد.

مقدار nodeset فهرستی از گره‌های numa است که توسط میزبان برای اجرای دامنه استفاده می‌شود. نحو آن به صورت یک فهرست جداشده با کاما است که در آن از '-' برای بازه‌ها و از '^' برای مستثنی کردن یک گره استفاده می‌شود.

اگر --live مشخص شده باشد، اطلاعات زمان‌بند یک مهمان در حال اجرا را تنظیم می‌کند. اگر --config مشخص شده باشد، بر راه‌اندازی بعدی یک مهمان ماندگار تأثیر می‌گذارد. اگر --current مشخص شده باشد، بسته به وضعیت فعلی مهمان معادل --live یا --config خواهد بود.

برای مهمان‌های در حال اجرا در میزبان‌های لینوکس، تغییرات اعمال‌شده در پارامترهای numa دامنه به این معنی نیست که حافظه مهمان بلافاصله به یک nodeset دیگر منتقل خواهد شد. مهاجرت حافظه به فعالیت مهمان بستگی دارد و حافظه یک مهمان بیکار برای مدت طولانی‌تری در nodeset قبلی خود باقی می‌ماند. همچنین حضور دستگاه‌های VFIO فارغ از تغییرات nodeset، بخش‌هایی از حافظه مهمان را در همان nodeset استفاده‌شده برای راه‌اندازی اولیه قفل خواهد کرد.

perf

نحو:

perf domain [--enable eventSpec] [--disable eventSpec]
   [[--config] [--live] | [--current]]

دریافت تنظیمات فعلی رویدادهای perf یا فعال/غیرفعال‌سازی رویدادهای مشخص perf برای یک دامنه مهمان.

ابزار Perf یک ابزار تحلیل عملکرد در لینوکس است و می‌تواند شمارنده‌های عملکرد CPU، نقاط ردگیری (tracepoints)، پروب‌های هسته (kprobes) و پروب‌های کاربر (uprobes - ردگیری پویا) را پایش کند. Perf از فهرستی از رویدادهای قابل اندازه‌گیری پشتیبانی می‌کند و می‌تواند رویدادهایی که از منابع گوناگون می‌آیند را بسنجد. برای مثال، برخی رویدادها شمارنده‌های خالص هسته هستند که در این حالت رویدادهای نرم‌افزاری نامیده می‌شوند، از جمله context-switches، minor-faults و غیره. امروزه ده‌ها رویداد از منابع مختلف توسط perf پشتیبانی می‌شوند.

در حال حاضر فقط QEMU/KVM از این دستور پشتیبانی می‌کند. گزینه‌های --enable و --disable در ترکیب با eventSpec می‌توانند برای فعال یا غیرفعال کردن رویدادهای عملکردی خاص استفاده شوند. مقدار eventSpec یک فهرست رشته‌ای از یک یا چند رویداد است که با کاما از هم جدا شده‌اند. نام‌های معتبر رویدادها به شرح زیر است:

نام‌های معتبر رویدادهای perf

نکته: آمارها را می‌توان با استفاده از دستور domstats و به همراه پرچم --perf بازیابی کرد.

اگر --live مشخص شده باشد، بر یک مهمان در حال اجرا تأثیر می‌گذارد. اگر --config مشخص شده باشد، بر راه‌اندازی بعدی یک مهمان ماندگار تأثیر می‌گذارد. اگر --current مشخص شده باشد، بسته به وضعیت فعلی مهمان معادل --live یا --config خواهد بود. هر دو پرچم --live و --config می‌توانند با هم ارائه شوند، اما --current مانعة‌الجمع است. در صورتی که هیچ پرچمی مشخص نشود، رفتار بسته به هایپروایزر متفاوت خواهد بود..SS reboot

نحو:

reboot domain [--mode MODE-LIST]

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

رفتار دقیق یک دامنه هنگام راه‌اندازی مجدد توسط پارامتر on_reboot در تعاریف XML دامنه تعیین می‌شود.

به طور پیش‌فرض هایپروایزر تلاش خواهد کرد یک روش خاموش‌سازی مناسب را انتخاب کند. برای مشخص کردن یک روش جایگزین، پارامتر --mode می‌تواند فهرستی جداشده با کاما را تعیین کند که شامل acpi، agent، initctl، signal و paravirt است. ترتیبی که درایورها هر حالت را امتحان می‌کنند نامشخص است و ارتباطی با ترتیب مشخص‌شده برای virsh ندارد. برای کنترل دقیق بر روی ترتیب، هر بار از یک حالت استفاده کرده و دستور را تکرار کنید.

reset

نحو:

reset domain

بازنشانی فوری یک دامنه بدون هیچ‌گونه خاموش‌سازی مهمان. دستور reset دکمه سخت‌افزاری بازنشانی (power reset) دستگاه را شبیه‌سازی می‌کند، که در آن تمام سخت‌افزارهای مهمان فعال شدن خط RST را دریافت کرده و وضعیت داخلی خود را مجدداً مقداردهی اولیه می‌کنند.

نکته: بازنشانی بدون خاموش‌سازی سیستم‌عامل مهمان خطر از دست رفتن داده‌ها را به همراه دارد.

restore

نحو:

restore state-file [--bypass-cache] [--xml file]
   [{--running | --paused}] [--reset-nvram] [--parallel-channels]

بازیابی یک دامنه از یک فایل وضعیت virsh save. برای اطلاعات بیشتر save را ببینید.

اگر --bypass-cache مشخص شده باشد، عملیات بازیابی از به‌کارگیری حافظه نهان (cache) سیستم فایل اجتناب می‌کند. بسته به سناریوی خاص، این کار ممکن است سرعت عملیات را کاهش یا افزایش دهد.

آرگومان --xml file معمولاً نادیده گرفته می‌شود، اما می‌تواند برای ارائه یک فایل XML جایگزین جهت استفاده روی مهمان بازیابی‌شده با اعمال تغییرات تنها در بخش‌های مربوط به میزبان در XML دامنه به کار رود. برای مثال، می‌توان از آن برای جبران تفاوت‌های نام‌گذاری فایل در فضای ذخیره‌سازی زیربنایی ناشی از اسنپ‌شات‌های دیسک گرفته‌شده پس از ذخیره دامنه استفاده کرد.

به طور معمول، بازیابی یک ایمیج ذخیره‌شده از وضعیت ثبت‌شده در تصویر ذخیره‌سازی برای تصمیم‌گیری بین حالت‌های در حال اجرا (running) یا متوقف (paused) استفاده می‌کند؛ ارسال هر یک از پرچم‌های --running یا --paused اجازه می‌دهد وضعیتی که دامنه باید با آن آغاز به کار کند بازنویسی (override) شود.

اگر --reset-nvram مشخص شود، هرگونه فایل موجود NVRAM/varstore حذف شده و از روی قالب اولیه و دست‌نخورده خود مجدداً مقداردهی اولیه می‌شود.

گزینه --parallel-channels می‌تواند تعداد کانال‌های موازی I/O را که هنگام بارگذاری حافظه از فایل استفاده می‌شوند مشخص کند. ذخیره‌سازی موازی ممکن است زمان مورد نیاز برای ذخیره دامنه‌های دارای حافظه بزرگ را به میزان چشمگیری کاهش دهد.

نکته: برای جلوگیری از خراب شدن محتویات سیستم فایل درون دامنه، نباید از فایل وضعیت ذخیره‌شده برای یک restore ثانویه استفاده کنید مگر اینکه تمام حجم‌های ذخیره‌سازی (storage volumes) را به همان محتوایی که هنگام ایجاد فایل وضعیت داشتند بازگردانده باشید..SS resume

نحو:

resume domain

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

save

نحو:

save domain state-file [--bypass-cache] [--xml file]
   [--image-format format]
   [--parallel-channels channels]
   [{--running | --paused}] [--verbose]

یک دامنهٔ در حال اجرا را (حافظهٔ RAM، اما نه وضعیت دیسک) در یک فایل وضعیت ذخیره می‌کند تا بتوان بعداً آن را بازیابی کرد. پس از ذخیره شدن، دامنه دیگر روی سیستم اجرا نخواهد شد، بنابراین حافظهٔ تخصیص‌یافته به دامنه برای استفادهٔ سایر دامنه‌ها آزاد می‌شود. دستور virsh restore از این فایل وضعیت بازیابی را انجام می‌دهد.

اگر --bypass-cache مشخص شود، عملیات ذخیره‌سازی از حافظهٔ موقت سیستم فایل چشم‌پوشی می‌کند. بسته به سناریوی خاص، این کار ممکن است سرعت عملیات را کاهش یا افزایش دهد.

پیشرفت عملیات را می‌توان با استفاده از دستور virsh با نام domjobinfo نظارت کرد و با دستور domjobabort (ارسال‌شده از یک نمونهٔ دیگر virsh) لغو نمود. گزینهٔ دیگر، ارسال SIGINT (معمولاً با Ctrl-C) به فرایند virsh در حال اجرای دستور save است. گزینهٔ --verbose پیشرفت ذخیره‌سازی را نمایش می‌دهد.

این عمل تقریباً معادل انجام خواب زمستانی (hibernate) روی یک رایانهٔ در حال اجرا با همان محدودیت‌ها است. اتصالات باز شبکه ممکن است هنگام بازیابی قطع شوند، زیرا ممکن است مهلت‌های زمانی TCP منقضی شده باشند.

آرگومان --xml file معمولاً نادیده گرفته می‌شود، اما می‌تواند برای ارائهٔ یک فایل XML جایگزین جهت استفاده در مهمان بازیابی‌شده با تغییراتی فقط در بخش‌های وابسته به میزبان در XML دامنه به کار رود. برای مثال، می‌توان از آن برای لحاظ کردن تفاوت‌های نام‌گذاری فایل که قرار است از طریق اسنپ‌شات‌های دیسک از فضای ذخیره‌سازی زیربنایی پس از ذخیره شدن مهمان اعمال شوند، استفاده کرد.

به‌طور معمول، بازیابی یک ایمیج ذخیره‌شده بر اساس وضعیتی که دامنه هنگام انجام ذخیره‌سازی در آن قرار داشت، بین در حال اجرا یا متوقف‌شده تصمیم‌گیری می‌کند؛ ارسال هر یک از پرچم‌های --running یا --paused امکان لغو و بازنویسی وضعیتی را که restore باید استفاده کند فراهم می‌کند.

گزینهٔ --image-format می‌تواند قالب پیش‌فرض ایمیج مورد استفاده برای ذخیرهٔ داده‌ها در فایل را تغییر دهد. برای جزئیات بیشتر به فایل پیکربندی qemu.conf مراجعه کنید.

گزینهٔ --parallel-channels می‌تواند تعداد کانال‌های موازی IO را که هنگام ذخیرهٔ حافظه در فایل استفاده می‌شوند مشخص کند. استفاده از کانال‌های موازی IO مستلزم استفاده از قالب ذخیره‌سازی ایمیج sparse است. ذخیره‌سازی موازی ممکن است زمان لازم برای ذخیرهٔ دامنه‌های دارای حافظهٔ بزرگ را به میزان قابل توجهی کاهش دهد.

فایل‌های وضعیت ذخیره‌شدهٔ دامنه فرض می‌کنند که ایمیج‌های دیسک بین نقطهٔ ایجاد و نقطهٔ بازیابی بدون تغییر باقی می‌مانند. برای یک نقطهٔ بازیابی کامل‌تر سیستم که در آن وضعیت دیسک در کنار وضعیت حافظه ذخیره می‌شود، خانوادهٔ دستورات snapshot را ببینید.

save-image-define

نحو:

save-image-define file xml [{--running | --paused}]

بخش XML دامنه را که هنگام استفادهٔ بعدی از file در دستور restore به کار می‌رود، به‌روزرسانی می‌کند. آرگومان xml باید نام فایلی حاوی XML جایگزین باشد که تغییرات آن فقط در بخش‌های وابسته به میزبان در XML دامنه اعمال شده باشد. برای مثال، می‌توان از آن برای لحاظ کردن تفاوت‌های نام‌گذاری فایل ناشی از ایجاد اسنپ‌شات‌های دیسک از فضای ذخیره‌سازی زیربنایی پس از ذخیره شدن مهمان استفاده کرد.

ایمیج ذخیره‌شده ثبت می‌کند که آیا دامنه باید در وضعیت در حال اجرا یا متوقف‌شده بازیابی شود. به‌طور معمول، این دستور وضعیت ثبت‌شده را تغییر نمی‌دهد؛ ارسال هر یک از پرچم‌های --running یا --paused امکان بازنویسی وضعیتی را که restore باید استفاده کند فراهم می‌کند..SS save-image-dumpxml

نحو:

save-image-dumpxml [--security-info] [--xpath EXPRESSION] [--wrap] file

استخراج XML دامنه که در زمان ایجاد فایل وضعیت ذخیره‌شدهٔ file با دستور save اعمال شده بود. استفاده از --security-info همچنین اطلاعات حساس امنیتی را نیز شامل خواهد شد.

اگر آرگومان --xpath یک عبارت XPath مشخص کند، بر روی XML خروجی ارزیابی خواهد شد و تنها گره‌های منطبق چاپ می‌شوند. رفتار پیش‌فرض چاپ هر گره منطبق به عنوان یک سند مستقل است؛ اما برای سهولت در پردازش‌های بیشتر، آرگومان --wrap باعث می‌شود که گره‌های منطبق در یک گره ریشه مشترک احاطه شوند.

save-image-edit

نحو:

save-image-edit file [{--running | --paused}]

ویرایش پیکربندی XML مرتبط با یک فایل وضعیت ذخیره‌شدهٔ file ایجادشده توسط دستور save.

تصویر ذخیره‌سازی ثبت می‌کند که آیا دامنه باید به وضعیت در حال اجرا (running) یا متوقف‌شده (paused) بازگردانده شود. به طور معمول، این دستور وضعیت ثبت‌شده را تغییر نمی‌دهد؛ ارسال هر یک از پرچم‌های --running یا --paused اجازه می‌دهد وضعیتی که restore باید استفاده کند بازنویسی شود.

این معادل است با:

virsh save-image-dumpxml state-file > state-file.xml
vi state-file.xml (or make changes with your other text editor)
virsh save-image-define state-file state-file-xml

با این تفاوت که برخی بررسی‌های خطا را انجام می‌دهد.

ویرایشگر مورداستفاده می‌تواند از طریق متغیرهای محیطی $VISUAL یا $EDITOR تعیین شود و مقدار پیش‌فرض آن vi است.

schedinfo

نحو:

schedinfo domain [[--config] [--live] | [--current]] [[--set] parameter=value]...
schedinfo [--weight number] [--cap number] domain

به شما امکان نمایش (و تنظیم) پارامترهای زمان‌بند دامنه را می‌دهد. پارامترهای موجود برای هر هایپروایزر عبارتند از:

LXC (زمان‌بند posix): cpu_shares, vcpu_period, vcpu_quota

QEMU/KVM (زمان‌بند posix): cpu_shares, vcpu_period, vcpu_quota, emulator_period, emulator_quota, global_period, global_quota, iothread_period, iothread_quota

Xen (زمان‌بند credit): weight, cap

ESX (زمان‌بند allocation): reservation, limit, shares

اگر --live مشخص شود، اطلاعات زمان‌بند یک مهمان در حال اجرا را تنظیم می‌کند. اگر --config مشخص شود، بر راه‌اندازی بعدی یک مهمان پایدار تأثیر می‌گذارد. اگر --current مشخص شود، بسته به وضعیت کنونی مهمان، معادل --live یا --config خواهد بود.

نکته: پارامتر cpu_shares در cgroups v1 دارای بازه مقدار معتبر 2-262144 و در cgroups v2 دارای بازه 1-10000 است.

نکته: پارامترهای weight و cap تنها برای زمان‌بند XEN_CREDIT تعریف شده‌اند.

نکته: پارامترهای vcpu_period، emulator_period و iothread_period دارای بازه مقدار معتبر 1000-1000000 یا 0 هستند، و پارامترهای vcpu_quota، emulator_quota و iothread_quota دارای بازه مقدار معتبر 1000-17592186044415 یا کمتر از 0 هستند. مقدار 0 برای هر یک از این پارامترها همانند عدم تعیین آن پارامتر است..SS screenshot

نحو:

screenshot domain [imagefilepath] [--screen screenID]

از کنسول دامنهٔ فعلی یک تصویر گرفته و آن را در یک فایل ذخیره می‌کند. به‌صورت اختیاری، در صورتی که هایپروایزر از چندین نمایشگر برای یک دامنه پشتیبانی کند، screenID امکان مشخص کردن صفحهٔ مورد نظر برای تصویربرداری را فراهم می‌سازد. این شناسه، شمارهٔ ترتیبی صفحه است. در صورت وجود چندین کارت گرافیک، هدها (heads) پیش از دستگاه‌ها شماره‌گذاری می‌شوند؛ برای نمونه در صورت داشتن دو کارت گرافیک که هر دو دارای چهار هد هستند، شناسهٔ صفحهٔ ۵ به دومین هد روی کارت دوم اشاره دارد.

send-key

نحو:

send-key domain [--codeset codeset] [--holdtime holdtime] keycode...

دنبالهٔ keycode را به عنوان ضربات کلید جهت ارسال به domain پردازش می‌کند. هر keycode می‌تواند یک مقدار عددی یا یک نام نمادین از codeset متناظر باشد. اگر --holdtime مشخص شده باشد، هر ضربهٔ کلید به همان میزان میلی‌ثانیه فشرده نگه داشته می‌شود. مجموعه کد (codeset) پیش‌فرض linux است، اما با استفاده از گزینهٔ --codeset می‌توان سایر codesetها را انتخاب کرد.

اگر چندین keycode مشخص شوند، همگی به‌صورت هم‌زمان به مهمان ارسال می‌گردند و ممکن است با ترتیبی تصادفی دریافت شوند. اگر به فشردن‌های مجزای کلید نیاز دارید، باید چندین بار دستور send-key را اجرا کنید.

مثال‌ها:

# ارسال سه کلید 'k'، 'e' و 'y' با استفاده از codeset مربوط به xt. همهٔ
# این‌ها به‌طور هم‌زمان فشرده می‌شوند و ممکن است توسط مهمان با ترتیبی تصادفی
# دریافت شوند
virsh send-key dom --codeset xt 37 18 21
# ارسال یک ضربهٔ کلید 'right-ctrl+C'
virsh send-key dom KEY_RIGHTCTRL KEY_C
# ارسال یک کلید tab، فشرده نگه‌داشته‌شده به مدت ۱ ثانیه
virsh send-key --holdtime 1000 0xf

send-process-signal domain-id pid signame

"nop", "hup", "int", "quit", "ill",
"trap", "abrt", "bus", "fpe", "kill",
"usr1", "segv", "usr2", "pipe", "alrm",
"term", "stkflt", "chld", "cont", "stop",
"tstp", "ttin", "ttou", "urg", "xcpu",
"xfsz", "vtalrm", "prof", "winch", "poll",
"pwr", "sys", "rt0", "rt1", "rt2", "rt3",
"rt4", "rt5", "rt6", "rt7", "rt8", "rt9",
"rt10", "rt11", "rt12", "rt13", "rt14", "rt15",
"rt16", "rt17", "rt18", "rt19", "rt20", "rt21",
"rt22", "rt23", "rt24", "rt25", "rt26", "rt27",
"rt28", "rt29", "rt30", "rt31", "rt32"

virsh send-process-signal myguest 1 15
virsh send-process-signal myguest 1 term
virsh send-process-signal myguest 1 sigterm
virsh send-process-signal myguest 1 SIG_HUP

set-lifecycle-action

نحو:

set-lifecycle-action domain type action
   [[--config] [--live] | [--current]]

تنظیم کنش چرخهٔ حیات (action) برای نوع چرخهٔ حیات (type) مشخص‌شده. انواع معتبر شامل "poweroff"، "reboot" و "crash" هستند و برای هر یک از آن‌ها، action معتبر یکی از موارد "destroy"، "restart"، "rename-restart" یا "preserve" است. برای type از نوع "crash"، کنش‌های اضافی "coredump-destroy" و "coredump-restart" نیز پشتیبانی می‌شوند.

set-user-password

نحو:

set-user-password domain user password [--encrypted]

تنظیم گذرواژه برای حساب کاربری user در دامنهٔ مهمان.

اگر --encrypted مشخص شده باشد، فرض می‌شود که گذرواژه از پیش با روش مورد نیاز سیستم‌عامل مهمان رمزنگاری شده است.

برای QEMU/KVM، این مورد نیازمند پیکربندی و در حال اجرا بودن عامل مهمان (guest agent) است..SS set-user-sshkeys

نحو:

set-user-sshkeys domain user [--file FILE] [{--reset | --remove}]

کلیدهای خوانده‌شده از FILE را به فایل کلیدهای مجاز SSH مربوط به user در دامنهٔ مهمان (domain) الحاق می‌کند. کلیدها در FILE باید در خطوط جداگانه باشند و هر خط باید از قالب کلیدهای مجاز تعریف‌شده توسط sshd(8) پیروی کند.

اگر --reset مشخص شده باشد، محتوای فایل کلیدهای مجاز مهمان پیش از الحاق کلیدهای جدید حذف می‌شود. به عنوان یک حالت ویژه، اگر --reset مشخص شده باشد و هیچ FILEی داده نشده باشد، کلید جدیدی اضافه نمی‌شود و فایل کلیدهای مجاز پاکسازی و خالی می‌گردد.

اگر --remove مشخص شده باشد، به جای افزودن هرگونه کلید جدید، کلیدهای خوانده‌شده از FILE از فایل کلیدهای مجاز حذف می‌شوند. در صورتی که کلید در فایل وجود نداشته باشد، خطا در نظر گرفته نمی‌شود.

setmaxmem

نحو:

setmaxmem domain size [[--config] [--live] | [--current]]

تغییر حد حداکثر تخصیص حافظه برای یک دامنهٔ مهمان. اگر --live مشخص شده باشد، بر یک مهمان در حال اجرا تأثیر می‌گذارد. اگر --config مشخص شده باشد، بر راه‌اندازی بعدی یک مهمان پایدار تأثیر می‌گذارد. اگر --current مشخص شده باشد، بسته به وضعیت فعلی مهمان، معادل با --live یا --config خواهد بود. هر دو پرچم --live و --config می‌توانند داده شوند، اما --current انحصاری است. اگر هیچ پرچمی مشخص نشود، رفتار برنامه بسته به هایپروایزر متفاوت خواهد بود.

برخی هایپروایزرها مانند QEMU/KVM از تغییرات زنده (به‌ویژه افزایش) حد حداکثر حافظه پشتیبانی نمی‌کنند. حتی ممکن است تغییرات پایدار پیکربندی نیز در برخی هایپروایزرها/پیکربندی‌ها انجام نشود (برای مثال در دامنه‌های با NUMA فعال روی QEMU). برای تغییرات پیکربندی پیچیده به جای آن از دستور edit استفاده کنید.

مقدار size یک عدد صحیح مقیاس‌پذیر است (بخش NOTES در بالا را ببینید)؛ پیش‌فرض آن کیبی‌بایت (بلوک‌های ۱۰۲۴ بایتی) است، مگر اینکه پسوندی ارائه دهید (و نام گزینهٔ قدیمی‌تر --kilobytes به عنوان یک مترادف منسوخ‌شده در دسترس است). Libvirt مقدار را به نزدیک‌ترین کیبی‌بایت به بالا گرد می‌کند. برخی هایپروایزرها به دانه‌بندی (granularity) بزرگ‌تری نسبت به KiB نیاز دارند و درخواست‌هایی که مضرب صحیحی از آن نباشند به بالا گرد می‌شوند. برای مثال، vSphere/ESX پارامتر را به مبی‌بایت (۱۰۲۴ کیبی‌بایت) به بالا گرد می‌کند.

setmem

نحو:

setmem domain size [[--config] [--live] | [--current]]

تغییر تخصیص حافظه برای یک دامنهٔ مهمان. اگر --live مشخص شده باشد، عملیات بالونینگ حافظه (memory ballooning) را روی یک مهمان در حال اجرا انجام می‌دهد. اگر --config مشخص شده باشد، بر راه‌اندازی بعدی یک مهمان پایدار تأثیر می‌گذارد. اگر --current مشخص شده باشد، بسته به وضعیت فعلی مهمان، معادل با --live یا --config خواهد بود. هر دو پرچم --live و --config می‌توانند با هم داده شوند، اما --current انحصاری است. اگر هیچ پرچمی مشخص نشود، رفتار برنامه بسته به هایپروایزر متفاوت خواهد بود.

مقدار size یک عدد صحیح مقیاس‌پذیر است (بخش NOTES در بالا را ببینید)؛ پیش‌فرض آن کیبی‌بایت (بلوک‌های ۱۰۲۴ بایتی) است، مگر اینکه پسوندی ارائه دهید (و نام گزینهٔ قدیمی‌تر --kilobytes به عنوان یک مترادف منسوخ‌شده در دسترس است). Libvirt مقدار را به نزدیک‌ترین کیبی‌بایت به بالا گرد می‌کند. برخی هایپروایزرها به دانه‌بندی بزرگ‌تری نسبت به KiB نیاز دارند و درخواست‌هایی که مضرب صحیحی از آن نباشند به بالا گرد می‌شوند. برای مثال، vSphere/ESX پارامتر را به مبی‌بایت (۱۰۲۴ کیبی‌بایت) به بالا گرد می‌کند.

برای Xen، تنها در صورتی می‌توانید حافظهٔ یک دامنهٔ در حال اجرا را تنظیم کنید که دامنه شبه‌مجازی‌سازی‌شده (paravirtualized) باشد یا گردانندهٔ بالون PV را اجرا کند.

برای LXC، مقداری که تنظیم می‌شود همان مقدار cgroups برای limit_in_bytes یا حداکثر میزان حافظهٔ کاربر (شامل حافظهٔ نهان فایل) است. هنگام مشاهدهٔ حافظه در داخل کانتینر، این همان مقدار "MemTotal" در /proc/meminfo است. هنگام مشاهدهٔ مقدار از سمت میزبان، از دستور virsh memtune استفاده کنید. جهت مشاهدهٔ حافظهٔ فعلی در حال استفاده و حداکثر مقدار مجاز برای تنظیم حافظه، از دستور virsh dominfo استفاده نمایید..SS setvcpus

نحو:

setvcpus domain count [--maximum] [[--config] [--live] | [--current]] [--guest] [--hotpluggable] [--async]

تعداد پردازنده‌های مجازی (vCPU) فعال در یک دامنهٔ مهمان را تغییر می‌دهد. به‌طور پیش‌فرض، این دستور روی دامنه‌های مهمان فعال کار می‌کند. برای تغییر تنظیمات یک دامنهٔ مهمان غیرفعال، از پرچم --config استفاده کنید.

مقدار count ممکن است توسط میزبان، هایپروایزر یا محدودیتی ناشی از توصیف اولیهٔ دامنهٔ مهمان محدود شود. برای Xen، تنها در صورتی می‌توانید پردازنده‌های مجازی یک دامنهٔ در حال اجرا را تنظیم کنید که دامنه به‌صورت شبه‌مجازی‌سازی‌شده (paravirtualized) باشد.

اگر پرچم --config مشخص شده باشد، تغییرات در پیکربندی ذخیره‌شدهٔ XML برای دامنهٔ مهمان اعمال می‌شود و تنها هنگام راه‌اندازی بعدی دامنهٔ مهمان تأثیر خواهد گذاشت.

اگر --live مشخص شده باشد، دامنهٔ مهمان باید فعال باشد و تغییر بلافاصله اعمال می‌شود. در صورت پشتیبانی هایپروایزر، هر دو پرچم --config و --live می‌توانند با هم مشخص شوند. اگر این دستور قبل از اتمام راه‌اندازی (بوت شدن) مهمان اجرا شود، ممکن است مهمان در پردازش این تغییر با شکست مواجه شود.

اگر --current مشخص شده باشد، بسته به وضعیت فعلی مهمان، معادل --live یا --config خواهد بود.

هنگامی که هیچ پرچمی داده نشود، پرچم --live فرض می‌شود و دامنهٔ مهمان باید فعال باشد. در این وضعیت، تصمیم‌گیری دربارهٔ اینکه آیا پرچم --config نیز فرض شود و در نتیجه پیکربندی XML برای دائمی کردن تغییرات تنظیم گردد یا خیر، بر عهدهٔ هایپروایزر است.

اگر --async مشخص شده باشد، درخواست‌های جدا کردن زندهٔ vCPU بدون انتظار برای موافقت و انطباق مهمان ارسال می‌شوند. تکمیل نهایی توسط رویداد دامنهٔ vcpu-removed گزارش می‌شود، در حالی که درخواست‌های جدا کردنِ رد شده همچنان توسط device-removal-failed گزارش خواهند شد. این پرچم را نمی‌توان با --guest ترکیب کرد.

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

برای مجاز ساختن افزودن vCPUها به تعاریف دائمی به‌گونه‌ای که بعداً پس از راه‌اندازی دامنه بتوان آن‌ها را به‌صورت زنده جدا کرد (hotunplug)، لازم است پرچم --hotpluggable مشخص شود. vCPUهای اضافه‌شده به دامنه‌های زنده‌ای که از جدا کردن vCPU پشتیبانی می‌کنند، به‌طور خودکار به‌عنوان hotpluggable علامت‌گذاری می‌شوند.

پرچم --maximum بیشترین تعداد پردازنده‌های مجازی را که می‌توان در راه‌اندازی بعدی دامنه به‌طور زنده متصل کرد (hot-plug)، کنترل می‌کند. از این رو، تنها باید به همراه پرچم --config استفاده شود، و نه با پرچم --live یا --current. توجه داشته باشید که اگر توپولوژی پردازنده برای مهمان مشخص شده باشد، ممکن است تغییر حداکثر تعداد vCPU امکان‌پذیر نباشد.

setvcpu

نحو:

setvcpu domain vcpulist [--enable] | [--disable] [--async]
   [[--live] [--config] | [--current]]

تغییر وضعیت تک‌تک vCPUها با استفاده از سازوکار اتصال/جداسازی زنده (hot(un)plug).

برای اطلاعات در مورد قالب vcpulist به vcpupin مراجعه کنید. درایورهای هایپروایزر ممکن است الزام کنند که vcpulist دقیقاً شامل vCPUهای متعلق به یک موجودیت با قابلیت اتصال زنده (hotpluggable) باشد. این مورد معمولاً فقط یک vCPU تکی است، اما معماری‌های خاصی مانند ppc64 نیاز دارند که یک هستهٔ کامل به‌طور هم‌زمان مشخص شود.

توجه داشته باشید که هایپروایزرها ممکن است از غیرفعال کردن برخی vCPUها مانند vcpu 0 یا موارد دیگر خودداری کنند.

اگر --live مشخص شود، بر یک دامنهٔ در حال اجرا اثر می‌گذارد. اگر --config مشخص شود، بر راه‌اندازی بعدی یک مهمان دائمی اثر می‌گذارد. اگر --current مشخص شود، بسته به وضعیت فعلی مهمان، معادل --live یا --config خواهد بود. این حالت پیش‌فرض است. هر دو پرچم --live و --config را می‌توان مشخص کرد، اما --current مانعة‌الجمع (انحصاری) است.

اگر --async همراه با --disable مشخص شود، درخواست‌های جدا کردن زندهٔ vCPU بدون انتظار برای انطباق مهمان ارسال می‌شوند. تکمیل نهایی این عملیات توسط رویداد دامنهٔ vcpu-removed گزارش می‌شود، در حالی که درخواست‌های جدا کردنِ رد شده همچنان توسط device-removal-failed گزارش خواهند شد..SS shutdown

نحو:

shutdown domain [--mode MODE-LIST]

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

رفتار دقیق دامنه هنگام خاموش شدن، توسط پارامتر on_poweroff در تعریف XML دامنه تعیین می‌شود.

اگر domain گذرا (transient) باشد، متادیتای هرگونه اسنپ‌شات و چک‌پوینت به محض توقف اجرای مهمان از بین خواهد رفت، اما محتویات زیرین همچنان باقی می‌مانند و یک دامنه جدید با همان نام و UUID می‌تواند متادیتای اسنپ‌شات را با snapshot-create و متادیتای چک‌پوینت را با checkpoint-create بازیابی کند.

به‌طور پیش‌فرض، هایپروایزر تلاش می‌کند روش مناسبی را برای خاموش‌سازی برگزیند. برای مشخص کردن روشی جایگزین، پارامتر --mode می‌تواند یک فهرست جداشده با کاما شامل acpi، agent، initctl، signal و paravirt را تعیین کند. ترتیبی که درایورها هر حالت را امتحان می‌کنند نامشخص است و ارتباطی با ترتیب مشخص‌شده برای virsh ندارد. برای کنترل دقیق روی ترتیب، در هر بار تنها از یک حالت استفاده کرده و دستور را تکرار کنید.

start

نحو:

start domain-name-or-uuid [--console] [--paused]
   [--autodestroy] [--bypass-cache] [--force-boot]
   [--pass-fds N,M,...] [--reset-nvram]

یک دامنه غیرفعال (از پیش تعریف‌شده) را یا از آخرین وضعیت ذخیره‌شده با managedsave یا در صورت نبود وضعیت ذخیره‌شده، از طریق یک بوت جدید راه‌اندازی می‌کند. اگر گزینه --paused استفاده شده و توسط درایور پشتیبانی شود، دامنه در حالت مکث (paused) قرار خواهد گرفت؛ در غیر این صورت در حال اجرا خواهد بود. اگر --console درخواست شده باشد، پس از ایجاد به کنسول متصل می‌شود. اگر --autodestroy مشخص شده باشد، با بسته شدن اتصال virsh به libvirt یا خروج از آن به هر نحوی، مهمان به‌طور خودکار نابود (destroyed) خواهد شد. اگر --bypass-cache مشخص شده باشد و وضعیت managedsave وجود داشته باشد، بازیابی بدون استفاده از حافظه پنهان (cache) سیستم فایل انجام می‌گیرد، گرچه ممکن است این کار سرعت عملیات را کاهش دهد. اگر --force-boot مشخص شده باشد، هرگونه وضعیت managedsave نادیده گرفته شده و یک بوت تازه انجام می‌شود.

اگر --pass-fds مشخص شده باشد، آرگومان مربوطه فهرستی جداشده با کاما از توصیف‌کننده‌های باز فایل است که باید به مهمان ارسال شوند. توصیف‌کننده‌های فایل در مهمان با شروع از ۳ شماره‌گذاری مجدد خواهند شد. این ویژگی تنها در مجازی‌سازی مبتنی بر کانتینر پشتیبانی می‌شود.

اگر --reset-nvram مشخص شده باشد، هرگونه فایل NVRAM/varstore موجود حذف شده و از روی قالب دست‌نخورده اولیه آن مجدداً مقداردهی اولیه می‌شود.

suspend

نحو:

suspend domain

یک دامنه در حال اجرا را به حالت تعلیق درمی‌آورد. دامنه در حافظه باقی می‌ماند اما دیگر زمان‌بندی و اجرا نخواهد شد..SS ttyconsole

نحو:

ttyconsole domain

دستگاه استفاده‌شده برای کنسول TTY دامنه را در خروجی نمایش می‌دهد. اگر اطلاعات در دسترس نباشد، فرایند با کد خروج 1 خاتمه می‌یابد.

undefine

نحو:

undefine domain [--managed-save] [--snapshots-metadata]
   [--checkpoints-metadata] [--nvram] [--keep-nvram]
   [ {--storage volumes | --remove-all-storage
      [--delete-storage-volume-snapshots]} --wipe-storage]
   [--tpm] [--keep-tpm]

تعریف یک دامنه را حذف می‌کند (undefine). اگر دامنه در حال اجرا باشد، بدون متوقف ساختن آن، آن را به یک دامنهٔ گذرا (transient) تبدیل می‌کند. اگر دامنه غیرفعال باشد، پیکربندی دامنه حذف می‌شود.

پرچم --managed-save تضمین می‌کند که هر تصویر ذخیره‌شدهٔ مدیریت‌شده (دستور managedsave را ببینید) نیز پاکسازی شود. بدون این پرچم، تلاش برای حذف تعریف دامنه‌ای که تصویر ذخیره‌شدهٔ مدیریت‌شده دارد، شکست خواهد خورد.

پرچم --snapshots-metadata تضمین می‌کند که هنگام حذف تعریف یک دامنهٔ غیرفعال، تمامی اسنپ‌شات‌ها (دستور snapshot-list را ببینید) نیز پاکسازی شوند. بدون این پرچم، تلاش برای حذف تعریف دامنهٔ غیرفعالی که متادیتای اسنپ‌شات دارد، با شکست مواجه خواهد شد. اگر دامنه فعال باشد، این پرچم نادیده گرفته می‌شود.

پرچم --checkpoints-metadata تضمین می‌کند که هنگام حذف تعریف یک دامنهٔ غیرفعال، تمامی نقاط بازرسی (دستور checkpoint-list را ببینید) نیز پاکسازی شوند. بدون این پرچم، تلاش برای حذف تعریف دامنهٔ غیرفعالی که متادیتای نقطه بازرسی دارد، با شکست مواجه خواهد شد. اگر دامنه فعال باشد، این پرچم نادیده گرفته می‌شود.

پرچم‌های --nvram و --keep-nvram به‌ترتیب تعیین می‌کنند که فایل NVRAM (/domain/os/nvram/) یا varstore (/domain/os/varstore) حذف یا نگه‌داری شود. اگر دامنه دارای یک فایل NVRAM/varstore باشد و این پرچم‌ها ذکر نشوند، عملیات حذف تعریف (undefine) ناموفق خواهد بود.

پرچم --storage پارامتر volumes را دریافت می‌کند، که فهرستی جداشده با کاما از نام‌های هدف جلد (volume target names) یا مسیرهای مبدأ جلدهای ذخیره‌سازی است که باید همراه با دامنهٔ تعریف‌زدوده حذف شوند. جلدها را تنها در دامنه‌های غیرفعال می‌توان از تعریف خارج و در نتیجه حذف کرد. تلاش برای حذف جلد تنها پس از حذف تعریف دامنه انجام می‌شود؛ اگر حذف همهٔ جلدهای درخواستی ممکن نباشد، پیام خطا موارد باقی‌مانده را مشخص می‌کند. اگر مسیر یک جلد در تعریف دامنه یافت نشود، به گونه‌ای برخورد می‌شود که گویی جلد با موفقیت حذف شده است. تنها جلدهایی که توسط libvirt در استخرهای ذخیره‌سازی مدیریت می‌شوند از این طریق قابل حذف هستند. توجه داشته باشید که این کار تنها تصویر سطح بالای یک زنجیرهٔ پشتیبان (backing chain) را حذف می‌کند و هرگونه مخزن پشتیبان (backing store) آن تصویر حفظ می‌شود، چرا که ممکن است مشترک باشد. (برای فهرست نام‌های هدف مرتبط با یک دامنه، به domblklist مراجعه کنید). مثال: --storage vda,/path/to/storage.img

پرچم --remove-all-storage مشخص می‌کند که تمام جلدهای ذخیره‌سازی دامنه باید به‌گونه‌ای حذف شوند که گویی از طریق --storage مشخص شده‌اند.

پرچم --delete-storage-volume-snapshots (پیش‌تر --delete-snapshots) مشخص می‌کند که تمام اسنپ‌شات‌های مرتبط با جلد ذخیره‌سازی نیز باید حذف شوند. این پرچم نیازمند ارائهٔ پرچم --remove-all-storage است. همهٔ درایورهای ذخیره‌سازی از این گزینه پشتیبانی نمی‌کنند؛ در حال حاضر تنها rbd پشتیبانی می‌شود. استفاده از این گزینه هنگام حذف جلدهایی که توسط یک درایور ذخیره‌سازیِ فاقد پشتیبانی از این پرچم مدیریت می‌شوند، به شکست می‌انجامد.

پرچم --wipe-storage مشخص می‌کند که جلدهای ذخیره‌سازی باید پیش از حذف به‌طور کامل پاک‌سازی و رونویسی (wipe) شوند.

--tpm و --keep-tpm به‌ترتیب حذف یا حفظ ساختار پوشه و فایل‌های وضعیت پایدار (persistent state) یک TPM را تعیین می‌کنند. اگر این پرچم‌ها ذکر نشوند، صفت persistent_state در تعریف شبیه‌ساز TPM در XML دامنه مشخص می‌کند که آیا وضعیت TPM نگه‌داری شود یا خیر.

یادداشت: برای یک دامنهٔ غیرفعال، باید از نام دامنه یا UUID به‌عنوان domain استفاده شود..SS vcpucount

نحو:

vcpucount domain  [{--maximum | --active}
   {--config | --live | --current}] [--guest]

اطلاعات مربوط به تعداد CPUهای مجازی (vCPU) domain مشخص‌شده را نمایش می‌دهد. اگر هیچ پرچمی مشخص نشود، تمام حالت‌های ممکنِ تعداد در یک جدول فهرست می‌شوند؛ در غیر این صورت، خروجی تنها به مقدار عددی درخواست‌شده محدود خواهد بود. به دلایل تاریخی، این جدول برچسب "current" را روی ردیف‌هایی قرار می‌دهد که می‌توان آن‌ها را به‌طور مجزا از طریق پرچم --active استعلام کرد، نه پرچم --current.

پرچم --maximum اطلاعات مربوط به سقف بیشینهٔ vCPUهایی را درخواست می‌کند که یک دامنه می‌تواند از طریق setvcpus اضافه کند، در حالی که --active میزان استفادهٔ کنونی را نشان می‌دهد؛ این دو پرچم نمی‌توانند هم‌زمان مشخص شوند. --config نیازمند یک مهمان پایدار (persistent) است و اطلاعات مربوط به دفعهٔ بعدی بوت شدن دامنه را استعلام می‌کند، --live نیازمند یک دامنهٔ در حال اجرا است و مقادیر فعلی را فهرست می‌کند، و --current بر اساس وضعیت کنونی دامنه استعلام می‌گیرد (در صورت در حال اجرا بودن معادل --live، و در صورت غیرفعال بودن معادل --config خواهد بود)؛ این سه پرچم مانعة‌الجمع هستند.

اگر --guest مشخص شود، تعداد پردازنده‌ها از دیدگاه سیستم‌عامل مهمان گزارش می‌شود. این پرچم تنها برای دامنه‌های در حال اجرا قابل استفاده است و ممکن است به پیکربندی guest agent در مهمان نیاز داشته باشد.

vcpuinfo

نحو:

vcpuinfo domain [--pretty]

اطلاعات پایه‌ای دربارهٔ پردازنده‌های مجازی دامنه، مانند تعداد vCPUها، زمان اجرا و وابستگی (affinity) به پردازنده‌های فیزیکی را برمی‌گرداند.

با استفاده از --pretty، وابستگی‌های پردازنده به صورت بازه نشان داده می‌شوند.

مثال:

$ virsh vcpuinfo fedora
VCPU:           0
CPU:            0
State:          running
CPU time:       7,0s
CPU Affinity:   yyyy
VCPU:           1
CPU:            1
State:          running
CPU time:       0,7s
CPU Affinity:   yyyy

وضعیت‌ها

فیلد State وضعیت عملیاتی کنونی یک پردازندهٔ مجازی را نمایش می‌دهد

vcpupin domain [vcpu] [cpulist] [[--live] [--config] | [--current]]

vncdisplay

نحو:

vncdisplay domain

آدرس IP و شماره درگاه (port) نمایشگر VNC را در خروجی چاپ می‌کند. در صورتی که این اطلاعات در دسترس نباشد، فرایندها کد خروج ۱ را برمی‌گردانند.

attach-device

نحو:

attach-device domain FILE [[[--live] [--config] | [--current]] | [--persistent]]

یک دستگاه را با استفاده از تعریف دستگاه در یک فایل XML و با استفاده از یک عنصر تعریف دستگاه مانند <disk> یا <interface> به عنوان عنصر سطح بالا (top-level) به دامنه ضمیمه می‌کند. برای آشنایی با قالب XML لایب‌ویرت (libvirt) برای یک دستگاه، مستندات موجود در https://libvirt.org/formatdomain.html#elementsDevices https://libvirt.org/formatdomain.html#devices را ببینید. اگر --config مشخص شده باشد، دستور پیکربندی پایدار مهمان را تغییر می‌دهد به طوری که ضمیمه شدن دستگاه در راه‌اندازی بعدی دامنه توسط libvirt اعمال می‌شود. برای دستگاه‌های cdrom و floppy، این دستور فقط رسانهٔ داخل یک دستگاه موجود را جایگزین می‌کند؛ برای این کاربرد، استفاده از update-device را مد نظر قرار دهید. برای دستگاه‌های عبوری میزبان (passthrough host devices)، همچنین nodedev-detach را ببینید، که در صورت عدم استفادهٔ دستگاه PCI از حالت مدیریت‌شده (managed mode) مورد نیاز است.

اگر --live مشخص شود، بر یک دامنه در حال اجرا تأثیر می‌گذارد. اگر --config مشخص شود، بر راه‌اندازی بعدی یک مهمان پایدار تأثیر می‌گذارد. اگر --current مشخص شود، بسته به وضعیت فعلی مهمان معادل --live یا --config خواهد بود. هر دو پرچم --live و --config می‌توانند هم‌زمان داده شوند، اما --current مانعة‌الجمع است. هنگامی که هیچ پرچمی مشخص نشود، از API قدیمی (legacy) استفاده می‌شود که رفتار آن به درایور hypervisor بستگی دارد.

به منظور سازگاری، --persistent برای یک دامنهٔ آفلاین مانند --config و برای یک دامنه در حال اجرا مانند --live --config عمل می‌کند.

نکته: استفاده از فایل‌های XML با تعریف جزئی دستگاه ممکن است به نتایج غیرمنتظره‌ای منجر شود، زیرا برخی فیلدها ممکن است به‌طور خودکار تولید شوند و در نتیجه با دستگاه‌هایی غیر از آنچه مورد انتظار است مطابقت پیدا کنند..SS attach-disk

نحو:

attach-disk domain source target [[[--live] [--config] |
   [--current]] | [--persistent]] [--targetbus bus]
   [--driver driver] [--subdriver subdriver] [--iothread iothread]
   [--cache cache] [--io io] [--type type] [--alias alias]
   [--mode mode] [--sourcetype sourcetype]
   [--source-protocol protocol] [--source-host-name hostname:port]
   [--source-host-transport transport] [--source-host-socket socket]
   [--serial serial] [--wwn wwn] [--rawio] [--address address]
   [--multifunction] [--print-xml] [--throttle-groups groups]

یک دستگاه دیسک جدید را به دامنه متصل می‌کند. مقدار source مسیر فایل‌ها و دستگاه‌ها است، مگر آنکه --source-protocol مشخص شده باشد که در این صورت source نام یک دیسک تحت شبکه خواهد بود. مقدار target گذرگاه یا دستگاهی را که دیسک تحت آن در دسترس سیستم‌عامل مهمان قرار می‌گیرد کنترل می‌کند. این مقدار نام دستگاه "منطقی" را نشان می‌دهد؛ مشخصهٔ اختیاری targetbus نوع دستگاه دیسک جهت شبیه‌سازی را تعیین می‌کند؛ مقادیر ممکن وابسته به درایور است و مقادیر متداول آن شامل ide، scsi، virtio، xen، usb، sata، یا sd می‌شود؛ در صورت حذف، نوع گذرگاه از روی الگوی نام دستگاه استنباط می‌شود (به عنوان مثال، دستگاهی به نام 'sda' معمولاً با استفاده از گذرگاه SCSI ارائه می‌شود). مقدار driver بسته به نوع دسترسی می‌تواند برای هایپروایزر Xen برابر با file، tap یا phy باشد؛ یا برای شبیه‌ساز QEMU برابر با qemu باشد. جزئیات بیشتر را می‌توان با استفاده از subdriver به درایور فرستاد. برای Xen مقدار subdriver می‌تواند aio باشد، در حالی که برای QEMU مقدار subdriver باید با قالب منبع دیسک، مانند raw یا qcow2 مطابقت داشته باشد. اگر subdriver مشخص نشود، از پیش‌فرض هایپروایزر استفاده خواهد شد. با این حال، مقدار پیش‌فرض ممکن است صحیح نباشد، به‌ویژه برای QEMU که بنا به دلایل امنیتی به‌گونه‌ای پیکربندی شده است که قالب دیسک را به طور خودکار تشخیص ندهد. مقدار type می‌تواند lun، cdrom یا floppy را به عنوان جایگزین پیش‌فرض دیسک نشان دهد، اگرچه این کاربرد صرفاً رسانه را درون دستگاه cdrom یا floppy مجازی موجود جایگزین می‌کند؛ برای چنین کاربردی استفاده از update-device را مد نظر قرار دهید. مقدار alias می‌تواند نام مستعار ارائه‌شده توسط کاربر را تنظیم کند. مقدار mode می‌تواند دو حالت مشخص readonly یا shareable را تعیین کند. مقدار sourcetype می‌تواند نوع منبع را مشخص کند (block|file|network). مقدار cache می‌تواند یکی از موارد "default"، "none"، "writethrough"، "writeback"، "directsync" یا "unsafe" باشد. مقدار io سیاست‌های خاص ورودی/خروجی (I/O) را کنترل می‌کند؛ مهمان‌های QEMU از "threads"، "native" و "io_uring" پشتیبانی می‌کنند. مقدار iothread شماره‌ای در محدودهٔ IOThreadهای دامنه است که این دیسک می‌تواند به آن متصل شود (فقط در QEMU). مقدار serial شماره سریال دستگاه دیسک است. wwn شناسهٔ wwn دستگاه دیسک است. گزینهٔ rawio نشان می‌دهد که دیسک به قابلیت rawio نیاز دارد. مقدار address نشانی دستگاه دیسک در قالب pci:domain.bus.slot.function، scsi:controller.bus.unit، ide:controller.bus.unit، usb:bus.port، sata:controller.bus.unit یا ccw:cssid.ssid.devno است. در دستگاه‌های virtio-ccw باید مقدار cssid بر روی 0xfe تنظیم شده باشد. گزینهٔ multifunction نشان می‌دهد که نشانی pci مشخص‌شده، نشانی یک دستگاه pci چندمنظوره است. مقدار throttle-groups فهرستی از گروه‌های کنترل نرخ مصرف (throttle groups) است که با کاما از هم جدا شده‌اند تا اعمال شوند.

همچنین پشتیبانی از استفاده از دیسک تحت شبکه وجود دارد. همان‌طور که بیان شد، کاربر می‌تواند گزینهٔ --source-protocol را تعیین کند که در این صورت پارامتر source به عنوان نام منبع تفسیر خواهد شد. در صورتی که کاربر قصد داشته باشد یک دیسک تحت شبکه یا اطلاعات میزبان را تعیین کند، گزینهٔ --source-protocol حتماً باید ارائه شود. اطلاعات میزبان را می‌توان با استفاده از برچسب‌های --source-host-name، --source-host-transport، و --source-host-socket ارائه داد، که به ترتیب نشان‌دهندهٔ نام میزبان، روش انتقال میزبان، و سوکتی هستند که میزبان استفاده می‌کند. نمی‌توان هر دو گزینهٔ --source-host-socket و --source-host-name را هم‌زمان ارائه داد، و اگر کاربر بخواهد --source-host-socket را تعیین کند، باید حتماً --source-host-transport را نیز مشخص نماید. پارامتر --source-host-name در صورتی که کاربر بخواهد درگاه را نیز ارائه دهد، از نحو host:port پشتیبانی می‌کند.

اگر --print-xml مشخص شود، به‌جای اتصال، ساختار XML دیسکی که قرار بود متصل شود چاپ می‌شود.

اگر --live مشخص شود، بر یک دامنهٔ در حال اجرا اثر می‌گذارد. اگر --config مشخص شود، بر راه‌اندازی بعدی یک مهمان ماندگار تأثیر می‌گذارد. اگر --current مشخص شود، بسته به وضعیت فعلی مهمان، معادل --live یا --config خواهد بود. هر دو پرچم --live و --config می‌توانند با هم مشخص شوند، اما --current انحصاری است. اگر هیچ پرچمی مشخص نشود، از API قدیمی استفاده می‌شود که رفتار آن به درایور هایپروایزر بستگی دارد.

به منظور سازگاری، --persistent برای یک دامنهٔ خاموش (آفلاین) مانند --config، و برای یک دامنهٔ در حال اجرا مانند --live --config رفتار می‌کند. به همین ترتیب، --shareable نام مستعاری برای --mode shareable است..SS attach-interface

ساختار:

attach-interface domain type source [[[--live]
   [--config] | [--current]] | [--persistent]]
   [--target target] [--mac mac] [--script script] [--model model]
   [--inbound average,peak,burst,floor] [--outbound average,peak,burst]
   [--alias alias] [--managed] [--print-xml]
   [--source-mode mode]

یک رابط شبکه جدید را به دامنه (domain) متصل می‌کند.

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

network برای نشان دادن اتصال از طریق یک شبکه مجازی libvirt،

bridge برای نشان دادن اتصال از طریق یک دستگاه پل (bridge) روی میزبان،

direct برای نشان دادن اتصال مستقیم به یکی از رابط‌های شبکه یا پل‌های میزبان،

hostdev برای نشان دادن اتصال با استفاده از انتقال مستقیم (passthrough) یک دستگاه PCI روی میزبان،

vhostuser برای نشان دادن اتصال با استفاده از پروتکل انتقال virtio.

پارامتر source منبع اتصال را مشخص می‌کند. این منبع به نوع رابط بستگی دارد:

network نام شبکه مجازی،

bridge نام دستگاه پل،

direct نام رابط یا پل میزبان،

hostdev آدرس PCI رابط میزبان در قالب domain:bus:slot.function.

vhostuser مسیر سوکت UNIX (صفحه کنترل)

گزینه --target برای مشخص کردن دستگاه tap/macvtap مورد استفاده جهت اتصال دامنه به منبع به کار می‌رود. نام‌هایی که با 'vnet' شروع می‌شوند، خودکار-تولیدشده در نظر گرفته شده و با هر بار اتصال رابط، پاک و مجدداً تولید می‌شوند.

گزینه --mac آدرس MAC رابط شبکه را مشخص می‌کند؛ اگر آدرس MAC ارائه نشود، یک آدرس جدید به‌طور خودکار تولید خواهد شد (و در صورتی که "--config" در خط فرمان داده شده باشد، در پیکربندی دائمی ذخیره می‌شود).

گزینه --script برای مشخص کردن مسیر یک اسکریپت سفارشی جهت فراخوانی هنگام اتصال به یک پل استفاده می‌شود - این اسکریپت به جای اسکریپت پیش‌فرض اجرا خواهد شد، نه علاوه بر آن. این گزینه فقط برای رابط‌های از نوع bridge و تنها برای دامنه‌های Xen معتبر است.

گزینه --model مدل دستگاه شبکه‌ای را که باید به دامنه ارائه شود مشخص می‌کند.

گزینه alias می‌تواند یک نام مستعار تعریف‌شده توسط کاربر را تنظیم کند.

گزینه‌های --inbound و --outbound پهنای باند رابط را کنترل می‌کنند. حداقل یکی از مقادیر جفت average و floor باید مشخص شود. دو مقدار دیگر یعنی peak و burst اختیاری هستند، بنابراین ساختارهای "average,peak"، "average,,burst"، "average,,,floor"، "average" و ",,,floor" نیز معتبر هستند. مقادیر average، floor و peak بر حسب کیبی‌بایت بر ثانیه (kiB) بیان می‌شوند، در حالی که burst بر حسب kiB در یک جهش منفرد با سرعت peak تعریف می‌شود، همان‌طور که در مستندات Network XML در https://libvirt.org/formatnetwork.html#quality-of-service شرح داده شده است.

گزینه --managed تنها برای نوع hostdev قابل استفاده است و به libvirt اعلام می‌کند که رابط باید مدیریت شود؛ به این معنی که جداسازی و اتصال مجدد آن از/به میزبان بر عهده libvirt خواهد بود.

گزینه --source-mode برای رابط vhostuser اجباری است و مقادیر server و client را می‌پذیرد که مشخص می‌کنند آیا هایپروایزر باید منتظر اتصال فرآیند دیگر بماند یا خودش اتصال را آغاز کند.

اگر --print-xml مشخص شود، به جای اتصال رابط، خروجی XML رابطی که قرار بود متصل شود چاپ خواهد شد.

اگر --live مشخص شود، روی دامنه در حال اجرا اعمال می‌شود. اگر --config مشخص شود، بر راه‌اندازی بعدی مهمان دائمی اعمال می‌شود. اگر --current مشخص شود، وضعیت فعلی دامنه (که می‌تواند زنده یا خاموش باشد) را تحت تأثیر قرار می‌دهد. هر دو پرچم --live و --config می‌توانند همزمان داده شوند، اما --current انحصاری است. در صورتی که هیچ پرچمی مشخص نشود، از API قدیمی استفاده می‌شود که رفتار آن به درایور هایپروایزر بستگی دارد.

به منظور سازگاری، پرچم --persistent برای یک دامنه خاموش رفتاری مشابه --config و برای یک دامنه در حال اجرا رفتاری مانند --live --config دارد.

نکته: مقدار اختیاری target، نام دستگاهی است که باید به عنوان پشت‌صحنه (back-end) روی گره ایجاد شود. اگر مشخص نشود، دستگاهی به نام "vnetN" یا "vifN" به‌طور خودکار ایجاد خواهد شد..SS detach-device

نحو:

detach-device domain FILE [[[--live] [--config] |
   [--current]] | [--persistent]]

یک دستگاه را از دامنه جدا می‌کند؛ این دستور همان نوع توصیف‌های XML را دریافت می‌کند که در دستور attach-device به کار می‌رود. برای دستگاه‌های میزبان گذرگاه (passthrough)، همچنین nodedev-reattach را ببینید؛ در صورتی که دستگاه از حالت مدیریت‌شده (managed mode) استفاده نکند، این دستور مورد نیاز است.

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

رفتار خاص: قطع اتصال فیزیکی دستگاه (unplug) در اغلب موارد ناهمگام (asynchronous) است و به همکاری سیستم‌عامل مهمان نیاز دارد. این یعنی رد کردن یا به تاخیر انداختن دلخواه عملیات قطع اتصال، کاملاً در اختیار سیستم‌عامل مهمان است. از آن‌جا که API ارائه‌شده توسط libvirt در این دستور به صورت همگام طراحی شده است، حتی اگر دستگاه هنوز جدا نشده باشد، پس از گذشت یک مهلت زمانی (timeout) وضعیت موفقیت‌آمیز را برمی‌گرداند تا تعامل‌های بعدی با دامنه امکان‌پذیر باشد؛ برای مثال، در مواردی که مهمان پاسخگو نیست. فراخوانندگانی که نیاز دارند از جدا شدن قطعی دستگاه اطمینان حاصل کنند، می‌توانند از رویدادهای libvirt (دستور virsh event را ببینید) استفاده کنند تا هنگام حذف دستگاه مطلع شوند. توجه داشته باشید که این رویداد ممکن است پیش از بازگشت دستور ارسال شود.

اگر --live مشخص شود، بر یک دامنهٔ در حال اجرا اثر می‌گذارد. اگر --config مشخص شود، در راه‌اندازی بعدی یک مهمان ماندگار اثر می‌گذارد. اگر --current مشخص شود، بسته به وضعیت فعلی مهمان، معادل با --live یا --config خواهد بود. هر دو پرچم --live و --config می‌توانند با هم مشخص شوند، اما --current انحصاری است. هنگامی که هیچ پرچمی مشخص نشده باشد، از API موروثی (قدیمی) استفاده می‌شود که رفتار آن به درایور هایپروایزر بستگی دارد.

به منظور سازگاری، --persistent برای یک دامنهٔ خاموش مانند --config و برای یک دامنهٔ در حال اجرا مانند --live --config رفتار می‌کند.

توجه داشته باشید که نسخه‌های قدیمی‌تر virsh از --config به عنوان نام مستعار --persistent استفاده می‌کردند.

detach-device-alias

نحو:

detach-device-alias domain alias [[[--live] [--config] | [--current]]]]

دستگاهی با alias داده‌شده را از domain جدا می‌کند. این دستور پس از ارسال درخواست جداسازی به هایپروایزر، با موفقیت بازمی‌گردد. حذف واقعی دستگاه به‌صورت ناهمگام از طریق رویدادهای libvirt اطلاع داده می‌شود (دستور virsh event را ببینید).

اگر --live مشخص شود، بر یک دامنهٔ در حال اجرا اثر می‌گذارد. اگر --config مشخص شود، در راه‌اندازی بعدی یک مهمان ماندگار اثر می‌گذارد. اگر --current مشخص شود، بسته به وضعیت فعلی مهمان، معادل با --live یا --config خواهد بود. هر دو پرچم --live و --config می‌توانند با هم مشخص شوند، اما --current انحصاری است.

detach-disk

نحو:

detach-disk domain target [[[--live] [--config] |
   [--current]] | [--persistent]] [--print-xml]

یک دستگاه دیسک را از یک دامنه جدا می‌کند. target دستگاهی است به همان شکلی که از سمت دامنه دیده می‌شود.

اگر --live مشخص شود، بر یک دامنهٔ در حال اجرا اثر می‌گذارد. اگر --config مشخص شود، در راه‌اندازی بعدی یک مهمان ماندگار اثر می‌گذارد. اگر --current مشخص شود، بسته به وضعیت فعلی مهمان، معادل با --live یا --config خواهد بود. هر دو پرچم --live و --config می‌توانند با هم مشخص شوند، اما --current انحصاری است. هنگامی که هیچ پرچمی مشخص نشده باشد، از API موروثی (قدیمی) استفاده می‌شود که رفتار آن به درایور هایپروایزر بستگی دارد.

به منظور سازگاری، --persistent برای یک دامنهٔ خاموش مانند --config و برای یک دامنهٔ در حال اجرا مانند --live --config رفتار می‌کند.

توجه داشته باشید که نسخه‌های قدیمی‌تر virsh از --config به عنوان نام مستعار --persistent استفاده می‌کردند.

اگر --print-xml مشخص شود، در عوض ساختار XML که برای جداسازی دیسک به کار می‌رفت چاپ می‌شود.

لطفاً برای آگاهی از رفتارهای خاص شناخته‌شده، مستندات detach-device را ببینید..SS detach-interface

نحو:

detach-interface domain [type] [--mac mac]
   [[[--live] [--config] | [--current]] | [--persistent]] [--print-xml]

یک رابط شبکه را از یک domain جدا می‌کند.

در صورتی که چندین رابط وجود داشته باشد، باید از type و/یا --mac برای محدود کردن انتخاب به ۱ رابط استفاده شود.

مقدار type می‌تواند network برای نشان دادن یک دستگاه شبکه فیزیکی یا bridge برای نشان دادن یک پل به دستگاه باشد.

گزینهٔ --mac می‌تواند رابط را بر اساس آدرس MAC پیکربندی‌شده انتخاب کند.

اگر --live مشخص شود، روی یک domain در حال اجرا اعمال می‌شود. اگر --config مشخص شود، بر راه‌اندازی بعدی یک مهمان پایدار تأثیر می‌گذارد. اگر --current مشخص شود، بسته به وضعیت فعلی مهمان، معادل --live یا --config خواهد بود. می‌توان هر دو پرچم --live و --config را هم‌زمان ارائه داد، اما --current انحصاری است. هنگامی که هیچ پرچمی مشخص نشده باشد، از API قدیمی استفاده می‌شود که رفتار آن به راه‌انداز hypervisor بستگی دارد.

به منظور سازگاری، --persistent برای یک domain خاموش مانند --config، و برای یک domain در حال اجرا مانند --live --config عمل می‌کند.

توجه داشته باشید که نسخه‌های قدیمی‌تر virsh از --config به عنوان نام مستعار برای --persistent استفاده می‌کردند.

اگر --print-xml مشخص شود، به جای انجام عمل جداسازی، XML استفاده‌شده برای جدا کردن رابط چاپ می‌شود.

لطفاً برای رفتارهای خاص شناخته‌شده، مستندات detach-device را ببینید.

update-device

نحو:

update-device domain file [--force] [[[--live]
   [--config] | [--current]] | [--persistent]]

ویژگی‌های یک دستگاه مرتبط با domain را بر اساس تعریف دستگاه در یک file با قالب XML به‌روزرسانی می‌کند. گزینهٔ --force می‌تواند برای اجبار به‌روزرسانی دستگاه استفاده شود؛ برای مثال خارج کردن یک CD-ROM حتی اگر در domain قفل یا متصل (mounted) باشد. برای آشنایی با ساختار XML ابزار libvirt برای یک دستگاه، مستندات موجود در https://libvirt.org/formatdomain.html#elementsDevices https://libvirt.org/formatdomain.html#devices را ببینید.

اگر --live مشخص شود، روی یک domain در حال اجرا اعمال می‌شود. اگر --config مشخص شود، بر راه‌اندازی بعدی یک مهمان پایدار تأثیر می‌گذارد. اگر --current مشخص شود، بسته به وضعیت فعلی مهمان، معادل --live یا --config خواهد بود. می‌توان هر دو پرچم --live و --config را مشخص کرد، اما --current انحصاری است. مشخص نکردن هیچ پرچمی همانند مشخص کردن --current است.

به منظور سازگاری، --persistent برای یک domain خاموش مانند --config، و برای یک domain در حال اجرا مانند --live --config عمل می‌کند.

توجه داشته باشید که نسخه‌های قدیمی‌تر virsh از --config به عنوان نام مستعار برای --persistent استفاده می‌کردند.

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

update-memory-device

نحو:

update-memory-device domain [--print-xml] [[--alias alias] | [--node node]]
  [[--live] [--config] | [--current]]
  [--requested-size size]

این دستور دستگاه <memory/> را در domain داده‌شده پیدا می‌کند، مقادیر درخواست‌شده را تغییر می‌دهد و XML به‌روزرسانی‌شدهٔ دستگاه را به daemon ارسال می‌کند. اگر --print-xml مشخص شود، دستگاه تغییر نمی‌کند، بلکه XML به‌روزرسانی‌شدهٔ دستگاه در stdout چاپ می‌شود. اگر بیش از یک دستگاه <memory/> در domain وجود داشته باشد، برای انتخاب مورد نظر از --alias یا --node استفاده کنید.

اگر --live مشخص شود، روی یک domain در حال اجرا اعمال می‌شود. اگر --config مشخص شود، بر راه‌اندازی بعدی یک مهمان پایدار تأثیر می‌گذارد. اگر --current مشخص شود، بسته به وضعیت فعلی مهمان، معادل --live یا --config خواهد بود. می‌توان هر دو پرچم --live و --config را مشخص کرد، اما --current انحصاری است. مشخص نکردن هیچ پرچمی همانند مشخص کردن --current است.

اگر --requested-size مشخص شود، مقدار <requested/> در بخش هدف حافظه به size درخواستی تغییر می‌یابد (به عنوان یک عدد صحیح مقیاس‌پذیر، NOTES در بالا را ببینید). در صورتی که هیچ پسوندی ارائه نشود، پیش‌فرض بر حسب kibibytes خواهد بود. این گزینه فقط برای مدل دستگاه حافظهٔ virtio-mem معتبر است..SS change-media

ساختار:

change-media domain path [--eject] [--insert]
   [--update] [source] [--force] [[--live] [--config] |
   [--current]] [--print-xml] [--block]

رسانه درایو CDROM یا فلاپی را تغییر می‌دهد. path می‌تواند مسیر کامل یا نام هدف یکتای (<target dev='hdc'>) دستگاه دیسک باشد. source مسیر رسانه‌ای که باید وارد یا به‌روزرسانی شود را مشخص می‌کند. پرچم --block امکان تعیین نوع پشتیبان (backing type) را در حالتی که به جای یک فایل از یک دستگاه بلوکی به عنوان رسانه درایو CDROM یا فلاپی استفاده می‌شود، فراهم می‌کند.

گزینه --eject مشخص می‌کند که رسانه خارج خواهد شد. گزینه --insert مشخص می‌کند که رسانه وارد خواهد شد. source باید مشخص شود. اگر دستگاه دارای منبع باشد (مانند <source file='media'>) و source مشخص نشده باشد، --update معادل --eject است. اگر دستگاه منبعی نداشته باشد و source مشخص شده باشد، --update معادل --insert است. اگر دستگاه دارای منبع باشد و source مشخص شده باشد، --update مانند ترکیبی از --eject و --insert عمل می‌کند. اگر هیچ‌یک از گزینه‌های --eject، --insert و --update مشخص نشده باشد، به‌طور پیش‌فرض از --update استفاده می‌شود. گزینه --force می‌تواند برای اجبار در تعویض رسانه استفاده شود. اگر --live مشخص شود، پیکربندی زنده مهمانِ در حال اجرا را تغییر می‌دهد. اگر --config مشخص شود، پیکربندی دائمی را تغییر می‌دهد و اثر آن در راه‌اندازی بعدی مهمان مشاهده خواهد شد. گزینه --current بسته به پیاده‌سازی hypervisor می‌تواند live، config یا هر دو باشد. هر دو پرچم --live و --config می‌توانند هم‌زمان داده شوند، اما --current انحصاری است. اگر هیچ پرچمی مشخص نشود، رفتار بسته به hypervisor متفاوت خواهد بود. اگر --print-xml مشخص شود، ساختار XML که قرار بود برای تغییر رسانه استفاده شود، به جای تغییر رسانه چاپ می‌شود.

dom-fd-associate

ساختار:

dom-fd-associate domain --name FDGROUPNAME --pass-fds M,N,....
    [--seclabel-writable] [--seclabel-restore]

یک یا چند توصیف‌گر فایل (fd) شرح‌داده‌شده با آرگومان --pass-fds را با نام --name به domain مرتبط می‌کند. طول عمر گروه fd ارسال‌شده با طول عمر اتصال یکسان است، بنابراین خروج از virsh پس از آن، ثبت آن‌ها را لغو می‌کند.

به‌طور پیش‌فرض، برچسب‌های امنیتی در صورت نیاز اعمال می‌شوند اما برای جلوگیری از باز نگه‌داشتن غیرضروری آن‌ها پس از استفاده بازیابی نمی‌شوند. با استفاده از پرچم --seclabel-restore می‌توان بازیابی با بیشترین تلاش (best-effort) برچسب امنیتی را درخواست کرد.

nodedev-update

نحو:

nodedev-update device FILE [[--live] [--config] | [--current]]

به‌روزرسانی یک دستگاه روی میزبان. device می‌تواند نام دستگاه یا جفت wwn در قالب "wwnn,wwpn" باشد (در حال حاضر فقط برای vHBA کار می‌کند). file حاوی xml برای توصیف سطح‌بالای <device> دستگاه گره است. بسته به پیاده‌سازی هایپروایزر، --current می‌تواند هر یک از live و config یا هر دوی آن‌ها باشد. هر دو پرچم --live و --config را می‌توان مشخص کرد، اما --current انحصاری است. اگر هیچ پرچمی مشخص نشود، رفتار بسته به هایپروایزر متفاوت خواهد بود.

nodedev-destroy

نحو:

nodedev-destroy device

تخریب (متوقف کردن) یک دستگاه روی میزبان. device می‌تواند نام دستگاه یا جفت wwn در قالب "wwnn,wwpn" باشد (در حال حاضر فقط برای vHBA کار می‌کند). توجه داشته باشید که این کار باعث می‌شود libvirt مدیریت دستگاه میزبان را متوقف کند، و حتی ممکن است آن دستگاه را تا زمان راه‌اندازی مجدد سیستم (reboot)، برای بقیه میزبان فیزیکی غیرقابل استفاده سازد.

nodedev-define

نحو:

nodedev-define FILE [--validate]

تعریف یک دستگاه ماندگار غیرفعال یا اصلاح یک دستگاه ماندگار موجود از روی FILE با قالب XML.

اگر --validate مشخص شده باشد، قالب سند XML را در برابر یک شِمای داخلی RNG اعتبارسنجی می‌کند.

nodedev-undefine

نحو:

nodedev-undefine device

حذف تعریف پیکربندی یک دستگاه ماندگار. اگر دستگاه فعال باشد، آن را به وضعیتی گذرا (transient) تغییر می‌دهد..SS nodedev-start

نحو:

nodedev-start device

یک دستگاه غیرفعال (از پیش تعریف‌شده) را راه‌اندازی می‌کند.

nodedev-detach

نحو:

nodedev-detach nodedev [--driver backend_driver]

دستگاه nodedev را از درایور میزبان جدا کرده و آن را به درایور ویژه‌ای متصل می‌کند که API مورد نیاز ناظر را برای تخصیص دستگاه به یک ماشین مجازی (با استفاده از <hostdev> در تعریف XML دامنه) فراهم می‌سازد. این عمل با دستور nodedev-reattach خنثی می‌شود، و برای دستگاه‌های مدیریت‌شده (دستگاه‌هایی با "managed='yes'" در تعریف XML آن‌ها) به‌طور خودکار توسط درایور ناظر انجام می‌گیرد.

ناظرهای مختلف انتظار دارند که دستگاه در حال تخصیص به درایورهای متفاوتی متصل شود. برای نمونه، بک‌اند "vfio" در QEMU نیازمند آن است که دستگاه به درایور "vfio-pci" یا یک درایور "واریانت VFIO" متصل شود (این درایوری است که علاوه بر API کامل ارائه‌شده توسط vfio-pci، از APIهای دیگری نیز برای پشتیبانی از قابلیت‌هایی نظیر مهاجرت زنده پشتیبانی می‌کند). پارامتر --driver می‌تواند برای مشخص کردن درایور خاصی (مثلاً یک درایور واریانت VFIO مختص دستگاه) که دستگاه باید به آن متصل گردد، استفاده شود. در صورت حذف --driver، درایور پیش‌فرض ناظر استفاده می‌شود ("vfio-pci" برای QEMU و "pciback" برای Xen).

nodedev-dumpxml

نحو:

nodedev-dumpxml [--inactive] [--xpath EXPRESSION] [--wrap] device

نمایش XML تگ <device> را برای دستگاه گره داده‌شده برون‌ریزی می‌کند؛ شامل اطلاعاتی نظیر نام دستگاه، گذرگاهی که دستگاه متعلق به آن است، شناسه سازنده و محصول، و هرگونه قابلیتی از دستگاه که توسط libvirt قابل استفاده باشد (مانند اینکه آیا بازنشانی دستگاه پشتیبانی می‌شود یا خیر). آرگومان device می‌تواند نام دستگاه یا یک جفت wwn در قالب "wwnn,wwpn" باشد (فقط برای HBA کار می‌کند). گزینه‌ی دیگری نیز که بر برون‌ریزی XML اثر می‌گذارد می‌تواند استفاده شود. گزینه --inactive به virsh می‌گوید تا پیکربندی دستگاه گره را که قرار است در راه‌اندازی بعدی دستگاه به کار رود، به جای پیکربندی فعلی آن برون‌ریزی کند.

اگر آرگومان --xpath یک عبارت XPath ارائه دهد، این عبارت بر روی خروجی XML ارزیابی شده و تنها گره‌های منطبق چاپ خواهند شد. رفتار پیش‌فرض این است که هر گره منطبق به عنوان یک سند مستقل چاپ شود، با این حال، جهت تسهیل پردازش‌های بیشتر، آرگومان --wrap سبب می‌شود که گره‌های منطبق در یک گره ریشه مشترک قرار گیرند.

nodedev-info

نحو:

nodedev-info device

اطلاعات پایه را درباره شیء device بازمی‌گرداند..SS nodedev-list

نحو:

nodedev-list [--cap capability] [--tree] [--inactive | --all] [--persistent | --transient]

تمام دستگاه‌های موجود روی گره را که توسط libvirt شناخته شده‌اند، فهرست می‌کند. از cap برای فیلتر کردن فهرست بر اساس نوع قابلیت‌ها استفاده می‌شود؛ نوع‌ها باید با کاما از هم جدا شوند، مانند --cap pci,scsi. انواع معتبر قابلیت‌ها شامل موارد زیر است: 'system'، 'pci'، 'usb_device'، 'usb'، 'net'، 'scsi_host'، 'scsi_target'، 'scsi'، 'storage'، 'fc_host'، 'vports'، 'scsi_generic'، 'drm'، 'mdev'، 'mdev_types'، 'ccw'، 'ccwgroup'، 'ccwgroup_member'، 'css'، 'ap_card'، 'ap_queue'، 'ap_matrix'. به‌طور پیش‌فرض، فقط دستگاه‌های فعال فهرست می‌شوند. گزینهٔ --inactive برای فهرست کردن فقط دستگاه‌های غیرفعال، و --all برای فهرست کردن هر دو گروه دستگاه‌های فعال و غیرفعال به کار می‌رود. --persistent برای فهرست کردن تنها دستگاه‌های پایدار، و --transient برای فهرست کردن تنها دستگاه‌های گذرا استفاده می‌شود. عدم ارائهٔ --persistent یا --transient باعث فهرست شدن تمام دستگاه‌ها می‌شود مگر اینکه فیلتر دیگری اعمال شده باشد. --transient با --persistent و --inactive مانعة‌الجمع است. در صورت استفاده از --tree، خروجی به‌صورت یک ساختار درختی که والدین هر گره را نشان می‌دهد قالب‌بندی می‌شود. --tree با تمام گزینه‌های دیگر به جز --all مانعة‌الجمع است.

nodedev-reattach

نحو:

nodedev-reattach nodedev

اعلام می‌کند که nodedev دیگر توسط هیچ میهمانی استفاده نمی‌شود و میزبان می‌تواند استفادهٔ عادی از دستگاه را از سر بگیرد. این عمل برای دستگاه‌های PCI در حالت مدیریت‌شده و دستگاه‌های USB به‌طور خودکار انجام می‌شود، اما برای مطابقت با هر nodedev-detach صریح، باید به‌صورت صریح انجام گیرد.

nodedev-reset

نحو:

nodedev-reset nodedev

یک بازنشانی دستگاه را برای nodedev راه‌اندازی می‌کند؛ این کار پیش از انتقال یک دستگاه گره بین حالت عبوردهی به میهمان (guest passthrough) یا میزبان مفید است. Libvirt اغلب در صورت لزوم این عمل را به‌طور ضمنی انجام می‌دهد، اما این دستور امکان بازنشانی صریح را در هنگام نیاز فراهم می‌سازد.

nodedev-event

نحو:

nodedev-event {[nodedev] event [--loop] [--timeout seconds] [--timestamp] | --list}

منتظر وقوع دسته‌ای از رویدادهای دستگاه گره می‌ماند و هم‌زمان با رخ دادن رویدادها، جزئیات مناسب آن‌ها را چاپ می‌کند. رویدادها را می‌توان به‌صورت اختیاری با nodedev فیلتر کرد. استفاده از --list به عنوان تنها آرگومان، فهرستی از مقادیر ممکن event را که برای این کلاینت شناخته‌شده هستند ارائه می‌دهد، هرچند ممکن است اتصال اجازهٔ ثبت‌نام برای همهٔ این رویدادها را ندهد.

به‌طور پیش‌فرض، این دستور یک‌باره (one-shot) عمل می‌کند و به محض وقوع یک رویداد وضعیت موفقیت را برمی‌گرداند؛ می‌توانید SIGINT (معمولاً از طریق Ctrl-C) ارسال کنید تا بلافاصله خارج شوید. اگر --timeout مشخص شده باشد، دستور پس از سپری شدن seconds ثانیه از انتظار برای رویدادها صرف‌نظر می‌کند. با --loop، دستور تمام رویدادها را تا زمان پایان مهلت زمانی یا کلید وقفه چاپ می‌کند.

هنگامی که از --timestamp استفاده شود، یک برچسب زمانی خوانا برای انسان پیش از رویداد چاپ خواهد شد..SS nodedev-autostart

نحو:

nodedev-autostart [--disable] device

پیکربندی یک دستگاه به‌گونه‌ای که هنگام بوت شدن ماشین میزبان یا دردسترس قرار گرفتن دستگاه والد، به‌طور خودکار آغاز به‌کار کند. با گزینهٔ --disable، دستگاه روی حالت دستی تنظیم می‌شود و دیگر به‌طور خودکار توسط میزبان راه‌اندازی نخواهد شد. این دستور فقط برای دستگاه‌های واسطه‌ای تعریف‌شده به‌طور ماندگار (persistently-defined mediated devices) پشتیبانی می‌شود.

net-autostart

نحو:

net-autostart network [--disable]

پیکربندی یک شبکه مجازی برای راه‌اندازی خودکار در هنگام بوت. گزینهٔ --disable راه‌اندازی خودکار را غیرفعال می‌کند.

net-create

نحو:

net-create file [--validate]

ایجاد یک شبکه مجازی گذرا (موقت) از روی یک file با فرمت XML و نمونه‌سازی (راه‌اندازی) شبکه. برای دریافت توضیحات دربارهٔ قالب XML شبکه که توسط libvirt استفاده می‌شود، به مستندات در https://libvirt.org/formatnetwork.html مراجعه کنید.

به‌صورت اختیاری، فرمت فایل XML ورودی می‌تواند با گزینهٔ --validate در برابر یک شمای RNG داخلی اعتبارسنجی شود.

net-define

نحو:

net-define file [--validate]

تعریف یک شبکه مجازی ماندگار غیرفعال یا اصلاح یک شبکه ماندگار موجود از روی file با فرمت XML. به‌صورت اختیاری، فرمت فایل XML ورودی می‌تواند با گزینهٔ --validate در برابر یک شمای RNG داخلی اعتبارسنجی شود.

net-desc

نحو:

net-desc network [[--live] [--config] |
   [--current]] [--title] [--edit] [--new-desc
   New description or title message]

نمایش یا تغییر توضیحات و عنوان یک شبکه. این مقادیر، فیلدهای کاربری هستند که امکان ذخیره داده‌های متنی دلخواه را برای شناسایی آسان‌تر شبکه‌ها فراهم می‌کنند. عنوان باید کوتاه باشد، هرچند که این موضوع اجباری نیست. (همچنین دستور net-metadata را ببینید که با فراداده‌های شبکه مبتنی بر XML کار می‌کند.)

پرچم‌های --live یا --config مشخص می‌کنند که این دستور بر روی تعاریف زنده یا ماندگار شبکه کار کند. اگر هر دو گزینهٔ --live و --config مشخص شوند، گزینهٔ --config در دریافت توضیحات فعلی اولویت دارد و هنگام تنظیم توضیحات، هم پیکربندی زنده و هم پیکربندی ماندگار به‌روزرسانی می‌شوند. --current انحصاری است و اگر هیچ‌یک از این گزینه‌ها تعیین نشده باشد، به‌صورت ضمنی اعمال می‌شود.

پرچم --edit مشخص می‌کند که یک ویرایشگر با محتویات توضیحات یا عنوان فعلی باز شود و محتویات پس از ویرایش مجدداً ذخیره گردند.

پرچم --title به‌جای فیلد توضیحات، عملیات را روی فیلد عنوان اعمال می‌کند.

اگر هیچ‌یک از پرچم‌های --edit و --new-desc مشخص نشده باشند، یادداشت یا توضیحات به‌جای ویرایش، نمایش داده می‌شوند..SS net-destroy

نحو:

net-destroy network

یک شبکه مجازی گذرا یا پایدار داده‌شده را که با نام یا UUID آن مشخص شده است، نابود (متوقف) می‌کند. این عمل بلافاصله اعمال می‌شود.

net-dumpxml

نحو:

net-dumpxml [--inactive] [--xpath EXPRESSION] [--wrap] network

اطلاعات شبکه مجازی را در قالب یک خروجی XML در stdout نمایش می‌دهد. اگر --inactive مشخص شده باشد، توابع فیزیکی به توابع مجازی مرتبط با خود بسط داده نمی‌شوند.

اگر آرگومان --xpath یک عبارت XPath را ارائه دهد، در برابر XML خروجی ارزیابی می‌شود و تنها گره‌های منطبق چاپ خواهند شد. رفتار پیش‌فرض، چاپ هر گره منطبق به عنوان یک سند مستقل است؛ با این حال، برای سهولت در پردازش‌های بیشتر، آرگومان --wrap باعث می‌شود که گره‌های منطبق درون یک گره ریشه مشترک قرار گیرند.

net-edit

نحو:

net-edit network

فایل پیکربندی XML را برای یک شبکه ویرایش می‌کند.

این معادل دستورهای زیر است:

virsh net-dumpxml --inactive network > network.xml
vi network.xml (or make changes with your other text editor)
virsh net-define network.xml

با این تفاوت که برخی بررسی‌های خطا را انجام می‌دهد.

ویرایشگر مورد استفاده می‌تواند توسط متغیرهای محیطی $VISUAL یا $EDITOR تعیین شود و پیش‌فرض آن vi است.

net-event

نحو:

net-event {[network] event [--loop] [--timeout seconds] [--timestamp] | --list}

منتظر وقوع دسته‌ای از رویدادهای شبکه می‌ماند و با رخ دادن رویدادها، جزئیات مناسب آن‌ها را چاپ می‌کند. رویدادها را می‌توان به‌صورت اختیاری بر اساس network فیلتر کرد. استفاده از --list به عنوان تنها آرگومان، فهرستی از مقادیر ممکن event را که برای این کلاینت شناخته‌شده است ارائه می‌دهد، اگرچه ممکن است اتصال اجازه ثبت‌نام برای همه این رویدادها را ندهد.

به‌طور پیش‌فرض، این دستور تک‌مرحله‌ای (one-shot) است و پس از وقوع یک رویداد با موفقیت به پایان می‌رسد؛ می‌توانید با ارسال SIGINT (معمولاً از طریق Ctrl-C) فوراً از آن خارج شوید. اگر --timeout مشخص شده باشد، دستور پس از سپری شدن seconds ثانیه از انتظار برای رویدادها صرف‌نظر می‌کند. با --loop، دستور تمام رویدادها را تا پایان مهلت زمانی یا فشردن کلید وقفه چاپ می‌کند.

هنگامی که از --timestamp استفاده شود، یک برچسب زمانی خوانا برای انسان قبل از رویداد چاپ خواهد شد..SS net-info

نحو:

net-info network

اطلاعات پایه‌ای درباره شیء network را برمی‌گرداند.

net-list

نحو:

net-list [--inactive | --all]
   { [--table] | --name | --uuid }
   [--persistent] [<--transient>]
   [--autostart] [<--no-autostart>]
   [--title]

فهرست شبکه‌های فعال را برمی‌گرداند؛ اگر --all مشخص شده باشد، شبکه‌های تعریف‌شده اما غیرفعال نیز در فهرست خواهند آمد، و اگر --inactive مشخص شده باشد، فقط موارد غیرفعال فهرست می‌شوند. همچنین می‌توانید شبکه‌های بازگردانده‌شده را با --persistent برای موارد مانگار، --transient برای موارد گذرا، --autostart برای مواردی که شروع خودکار آن‌ها فعال است، و --no-autostart برای مواردی با شروع خودکار غیرفعال فیلتر کنید.

اگر --name مشخص شده باشد، نام‌های شبکه‌ها به جای قالب جدولی و در هر سطر یک نام چاپ می‌شوند. اگر --uuid مشخص شده باشد، به جای نام‌ها، UUID'های شبکه چاپ می‌شوند. پرچم --table مشخص می‌کند که از خروجی سنتی با قالب جدول استفاده شود. این حالت پیش‌فرض است. همه این پرچم‌ها مانعة‌الجمع هستند.

اگر --title مشخص شده باشد، شرح کوتاه شبکه (عنوان) در یک ستون اضافی چاپ می‌شود. این پرچم فقط همراه با خروجی پیش‌فرض --table قابل استفاده است.

نکته: هنگام برقراری ارتباط با کارگزارهای قدیمی‌تر، این دستور ناچار است از مجموعه‌ای از فراخوانی‌های API با شرایط رقابتی ذاتی (race condition) استفاده کند که در آن ممکن است در صورت تغییر وضعیت یک pool میان فراخوانی‌ها در حین گردآوری فهرست، آن مورد در فهرست ظاهر نشود یا بیش از یک بار ظاهر شود. کارگزارهای جدیدتر این مشکل را ندارند.

net-metadata

نحو:

net-metadata network [[--live] [--config] | [--current]]
   [--edit] [uri] [key] [set] [--remove]

نمایش یا ویرایش متاداده‌های سفارشی XML یک شبکه. متاداده یک XML تعریف‌شده توسط کاربر است که امکان ذخیره‌سازی داده‌های دلخواه XML را در تعریف شبکه فراهم می‌کند. چندین بخش جداگانه از متاداده‌های سفارشی می‌توانند در XML شبکه ذخیره شوند. این بخش‌ها با یک فضای‌نام (namespace) اختصاصی XML که از طریق آرگومان uri ارائه می‌شود، شناسایی می‌گردند. (همچنین دستور net-desc را ببینید که با متاداده‌های متنی شبکه، مانند عنوان و توضیحات کار می‌کند.)

پرچم‌های --live یا --config تعیین می‌کنند که این دستور بر روی تعاریف زنده یا مانگار شبکه عمل کند. اگر هر دو پرچم --live و --config مشخص شده باشند، گزینه --config در دریافت توضیحات فعلی اولویت دارد و هنگام تنظیم توضیحات، هم پیکربندی زنده و هم config به‌روزرسانی می‌شوند. --current مانعة‌الجمع است و در صورتی که هیچ‌یک مشخص نشده باشند، به صورت ضمنی اعمال می‌شود.

پرچم --remove مشخص می‌کند که عنصر متاداده تعیین‌شده توسط آرگومان uri باید به جای به‌روزرسانی، حذف شود.

پرچم --edit مشخص می‌کند که یک ویرایشگر حاوی متاداده شناسایی‌شده با آرگومان uri باز شود و محتویات پس از آن ذخیره گردند. در غیر این صورت، محتوای جدید می‌تواند از طریق آرگومان set ارائه شود.

هنگام تنظیم متاداده از طریق --edit یا set، آرگومان key باید مشخص شود و برای پیشوندگذاری عنصرهای سفارشی جهت پیوند دادن آن‌ها به فضای‌نام اختصاصی به کار می‌رود.

اگر هیچ‌کدام از --edit و set مشخص نشده باشند، متاداده XML متناظر با فضای‌نام uri به جای ویرایش، نمایش داده می‌شود..SS net-name

سینتکس:

net-name network-UUID

تبدیل یک UUID شبکه به نام شبکه.

net-start

سینتکس:

net-start network

راه‌اندازی یک شبکه غیرفعال (از پیش تعریف‌شده).

net-undefine

سینتکس:

net-undefine network

حذف تعریف پیکربندی یک شبکه مانا (persistent). اگر شبکه فعال باشد، آن را به یک شبکه گذرا (transient) تبدیل می‌کند.

net-uuid

سینتکس:

net-uuid network-name

تبدیل یک نام شبکه به UUID شبکه.

net-update

سینتکس:

net-update network command section xml
   [--parent-index index] [[--live] [--config] | [--current]]

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

دستور command یکی از موارد "add-first"، "add-last"، "add" (مترادفی برای add-last)، "delete" یا "modify" است.

بخش section یکی از موارد "bridge"، "domain"، "ip"، "ip-dhcp-host"، "ip-dhcp-range"، "forward"، "forward-interface"، "forward-pf"، "portgroup"، "dns-host"، "dns-txt" یا "dns-srv" است؛ نام هر بخش از الحاق سلسله‌مراتب عنصرهای xml منتهی به عنصری که تغییر می‌یابد تشکیل شده است. برای نمونه، "ip-dhcp-host" عنصر <host> را که درون یک عنصر <dhcp> داخل یک عنصر <ip> از شبکه قرار دارد، تغییر خواهد داد.

مقدار xml یا متن یک عنصر کامل xml از همان نوعی است که تغییر داده می‌شود (مانند "<host mac="00:11:22:33:44:55' ip='1.2.3.4'/>") یا نام فایلی است که دربردارنده یک عنصر کامل xml است. رفع ابهام با بررسی نخستین نویسه متن ارائه‌شده انجام می‌شود - اگر نویسه نخست "<" باشد، به عنوان متن xml در نظر گرفته می‌شود؛ اگر نویسه نخست "<" نباشد، نام فایلی است که حاوی متن xml مورد استفاده می‌باشد.

گزینه --parent-index برای مشخص کردن این که عنصر درخواستی در کدام‌یک از چندین عنصر والد قرار دارد استفاده می‌شود (مبتنی بر صفر). برای نمونه، یک عنصر dhcp <host> می‌تواند در هر یک از چندین عنصر <ip> درون شبکه باشد؛ اگر parent-index ارائه نشود، "مناسب‌ترین" عنصر <ip> انتخاب خواهد شد (معمولاً تنها عنصری که از قبل حاوی یک عنصر <dhcp> است)، اما اگر --parent-index مشخص شود، آن نمونه خاص از <ip> دستخوش تغییر خواهد شد.

اگر --live مشخص شود، بر روی یک شبکه در حال اجرا اثر می‌گذارد. اگر --config مشخص شود، بر روی راه‌اندازی بعدی یک شبکه مانا اثر می‌گذارد. اگر --current مشخص شود، بسته به وضعیت کنونی مهمان، معادل --live یا --config خواهد بود. هر دو پرچم --live و --config را می‌توان با هم تعیین کرد، اما --current مانعة‌الجمع (انحصاری) است. مشخص نکردن هیچ پرچمی همانند تعیین --current است..SS net-dhcp-leases

نحو:

net-dhcp-leases network [mac]

دریافت فهرستی از اجاره‌های dhcp برای تمام رابط‌های شبکه متصل به network مجازی داده‌شده، یا محدود کردن خروجی تنها به یک رابط در صورتی که mac مشخص شده باشد.

net-port-list

نحو:

net-port-list { [--table] | --uuid } network

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

اگر --uuid مشخص شود، به‌جای جدول، UUIDهای درگاه‌های شبکه چاپ می‌شوند. پرچم --table مشخص می‌کند که باید از خروجی سنتی جدول‌بندی‌شده استفاده شود. این حالت پیش‌فرض است. تمام این موارد مانعة‌الجمع هستند.

net-port-create

نحو:

net-port-create network file [--validate]

تخصیص یک درگاه شبکه جدید و رزرو منابع بر اساس توصیف درگاه. به‌صورت اختیاری، قالب فایل XML ورودی می‌تواند با --validate در برابر یک طرح‌وارهٔ (schema) داخلی RNG اعتبارسنجی شود.

net-port-dumpxml

نحو:

net-port-dumpxml [--xpath EXPRESSION] [--wrap] network port

چاپ اطلاعات درگاه شبکه به‌صورت یک دامپ XML در stdout.

اگر آرگومان --xpath یک عبارت XPath ارائه دهد، در برابر XML خروجی ارزیابی خواهد شد و تنها گره‌های منطبق چاپ می‌شوند. رفتار پیش‌فرض این است که هر گرهٔ منطبق به‌صورت یک سند مستقل چاپ شود، اما برای سهولت در پردازش‌های بیشتر، آرگومان --wrap باعث می‌شود که گره‌های منطبق درون یک گره ریشه مشترک قرار داده شوند.

net-port-delete

نحو:

net-port-delete network port

حذف رکورد درگاه شبکه و آزادسازی منابع آن..SH "دستورهای رابط (INTERFACE COMMANDS)"

دستورهای زیر رابط‌های میزبان را مدیریت می‌کنند. اغلب می‌توان این رابط‌های میزبان را با نام در عناصر <interface> دامنه (مانند یک رابط bridge ایجادشده توسط سیستم) استفاده کرد، اما هیچ الزامی وجود ندارد که رابط‌های میزبان حتماً به یک پیکربندی XML مهمان خاص مرتبط باشند.

بسیاری از دستورهای مربوط به رابط‌های میزبان شبیه به دستورهای مورد استفاده برای دامنه‌ها هستند، و روش نام‌گذاری یک رابط با استفاده از نام آن یا آدرس MAC آن است. با این حال، استفاده از آدرس MAC برای یک آرگومان iface تنها زمانی کار می‌کند که آن آدرس یکتا باشد (اگر یک رابط و یک bridge دارای آدرس MAC یکسانی باشند، که اغلب نیز چنین است، استفاده از آن آدرس MAC به دلیل ابهام منجر به خطا می‌شود و در عوض باید به نام متوسل شوید).

iface-bridge

نحو:

iface-bridge interface bridge [--no-stp] [delay] [--no-start]

یک دستگاه bridge به نام bridge ایجاد می‌کند، و دستگاه شبکه موجود interface را به bridge جدید متصل می‌نماید. bridge جدید به‌طور پیش‌فرض بلافاصله با STP فعال و تاخیر 0 شروع به کار می‌کند؛ این تنظیمات را می‌توان با --no-stp، --no-start و یک عدد صحیح به ثانیه برای delay تغییر داد. تمام پیکربندی آدرس IP مربوط به interface به دستگاه bridge جدید منتقل خواهد شد.

همچنین برای لغو این عملیات، iface-unbridge را ببینید.

iface-define

نحو:

iface-define file [--validate]

یک رابط فیزیکی میزبانِ ماندگار و غیرفعال را تعریف می‌کند یا یک رابط ماندگار موجود را از روی file با ساختار XML تغییر می‌دهد. در صورت تمایل، قالب فایل XML ورودی را می‌توان با گزینه --validate در برابر یک شمای RNG داخلی اعتبارسنجی کرد.

iface-destroy

نحو:

iface-destroy interface

یک رابط میزبان مشخص‌شده را نابود (متوقف) می‌کند، مانند اجرای "if-down" برای از کار انداختن آن رابط از حالت استفاده فعال. این عمل بلافاصله اعمال می‌شود.

iface-dumpxml

نحو:

iface-dumpxml [--inactive] [--xpath EXPRESSION] [--wrap] interface

اطلاعات رابط میزبان را به صورت یک خروجی ساختاریافته XML در stdout می‌ریزد. اگر --inactive مشخص شده باشد، خروجی نمایانگر وضعیت ماندگار رابط خواهد بود که در راه‌اندازی بعدی از آن استفاده می‌شود.

اگر آرگومان --xpath یک عبارت XPath ارائه دهد، آن عبارت بر روی خروجی XML ارزیابی شده و تنها گره‌های منطبق چاپ خواهند شد. رفتار پیش‌فرض این است که هر گره منطبق به عنوان یک سند مستقل چاپ شود؛ با این حال، برای سهولت در پردازش‌های بیشتر، آرگومان --wrap باعث می‌شود که گره‌های منطبق درون یک گره ریشه مشترک قرار داده شوند..SS iface-edit

ساختار:

iface-edit interface

ویرایش فایل پیکربندی XML برای یک رابط میزبان.

این معادل است با:

virsh iface-dumpxml iface > iface.xml
vi iface.xml (or make changes with your other text editor)
virsh iface-define iface.xml

با این تفاوت که برخی بررسی‌های خطا را انجام می‌دهد.

ویرایشگر مورداستفاده می‌تواند از طریق متغیرهای محیطی $VISUAL یا $EDITOR مشخص شود و مقدار پیش‌فرض آن vi است.

iface-list

ساختار:

iface-list [--inactive | --all]

فهرست رابط‌های فعال میزبان را بازمی‌گرداند. اگر --all مشخص شده باشد، رابط‌های تعریف‌شده اما غیرفعال نیز شامل خواهند شد. اگر --inactive مشخص شده باشد، تنها موارد غیرفعال فهرست می‌شوند.

iface-name

ساختار:

iface-name interface

تبدیل آدرس MAC رابط میزبان به نام رابط، در صورتی که آدرس MAC در میان رابط‌های میزبان یکتا باشد.

پارامتر interface آدرس MAC رابط را مشخص می‌کند.

iface-mac

ساختار:

iface-mac interface

تبدیل نام یک رابط میزبان به آدرس MAC.

پارامتر interface نام رابط را مشخص می‌کند.

iface-start

ساختار:

iface-start interface

راه‌اندازی یک رابط میزبان (از قبل تعریف‌شده)، مانند اجرای "if-up"..SS iface-unbridge

نحو:

iface-unbridge bridge [--no-start]

برچیدن یک دستگاه پل (bridge) به نام bridge، آزادسازی رابط زیربنایی آن برای استفادهٔ عادی، و انتقال تمام پیکربندی‌های آدرس IP از دستگاه پل به دستگاه زیربنایی. رابط زیربنایی مجدداً راه‌اندازی می‌شود مگر اینکه --no-start داده شده باشد؛ این پرچم جهت تقارن ساختاری وجود دارد، اما عموماً توصیه نمی‌شود.

همچنین برای ایجاد یک پل، iface-bridge را ببینید.

iface-undefine

نحو:

iface-undefine interface

حذف تعریف (undefine) پیکربندی یک رابط میزبان غیرفعال.

iface-begin

نحو:

iface-begin

ایجاد یک تصویر لحظه‌ای (snapshot) از تنظیمات کنونی رابط میزبان، که بعداً می‌تواند تثبیت (iface-commit) یا بازگردانی (iface-rollback) شود. اگر از قبل یک تصویر لحظه‌ای وجود داشته باشد، این دستور تا زمانی که تصویر لحظه‌ای قبلی تثبیت یا بازگردانی نشود با خطا مواجه خواهد شد. در صورتی که در فاصلهٔ بین شروع یک تصویر لحظه‌ای و تثبیت یا بازگردانی نهایی آن، تغییراتی خارج از API لایب‌ویرت (libvirt) روی رابط‌های میزبان صورت گیرد، رفتاری تعریف‌نشده در پی خواهد داشت.

iface-commit

نحو:

iface-commit

تأیید و نهایی‌سازی تمامی تغییرات اعمال‌شده از زمان آخرین iface-begin و حذف نقطهٔ بازگردانی. اگر از قبل هیچ تصویر لحظه‌ای برای رابط آغاز نشده باشد، این دستور با خطا مواجه خواهد شد.

iface-rollback

نحو:

iface-rollback

بازگردانی تمام تنظیمات رابط میزبان به وضعیتی که در آخرین iface-begin ثبت شده است. اگر از قبل هیچ تصویر لحظه‌ای برای رابط آغاز نشده باشد، این دستور با خطا مواجه خواهد شد. راه‌اندازی مجدد میزبان نیز به عنوان یک نقطهٔ بازگردانی ضمنی عمل می‌کند..SH "دستورهای استخر ذخیره‌سازی (STORAGE POOL COMMANDS)"

دستورهای زیر استخرهای ذخیره‌سازی را مدیریت می‌کنند. Libvirt قابلیت مدیریت راهکارهای گوناگون ذخیره‌سازی، از جمله فایل‌ها، پارتیشن‌های خام (raw partitions) و قالب‌های ویژهٔ دامنه‌ها را دارد که برای فراهم کردن حجم‌های ذخیره‌سازی (storage volumes) به عنوان دستگاه‌ها در ماشین‌های مجازی به کار می‌روند. برای اطلاعات دقیق‌تر درباره این ویژگی، مستندات را در https://libvirt.org/formatstorage.html ببینید. بسیاری از دستورهای مربوط به استخرها مشابه دستورهای مورد استفاده برای دامنه‌ها هستند.

find-storage-pool-sources

نحو:

find-storage-pool-sources type [srcSpec]

یک خروجی XML برمی‌گرداند که تمام منابع موجود و ممکن برای استخر ذخیره‌سازی را شرح می‌دهد که می‌توان از آن‌ها برای ایجاد یا تعریف یک استخر ذخیره‌سازی از یک type معین استفاده کرد. اگر srcSpec ارائه شود، فایلی شامل XML است تا پرس‌وجوی استخرها را محدودتر کند.

همه استخرهای ذخیره‌سازی از شناسایی (discovery) به این روش پشتیبانی نمی‌کنند. علاوه بر این، برای استخرهایی که از شناسایی پشتیبانی می‌کنند، تنها عنصرهای XML خاصی برای بازگرداندن داده‌های معتبر الزامی هستند، در حالی که عنصرهای دیگر و حتی مشخصه‌های برخی عناصر نادیده گرفته می‌شوند، زیرا بر اساس معیارهای جستجو برای یافتن استخر ضروری نیستند. موارد زیر گزینه‌های پشتیبانی‌شدهٔ type و حداقل عنصرهای XML مورد انتظار برای انجام جستجو را فهرست می‌کنند.

برای یک استخر "netfs" یا "gluster"، حداقل XML مورد انتظار عنصر <host> با مشخصهٔ "name" است که آدرس IP یا نام میزبان (hostname) را برای یافتن استخر توصیف می‌کند. مشخصهٔ "port" و نیز هر عنصر XML دیگری که در srcSpec ارائه شود، نادیده گرفته خواهند شد.

برای یک استخر "logical"، محتویات فایل srcSpec نادیده گرفته می‌شود، اگرچه در صورت ارائه، این فایل دست‌کم باید وجود داشته باشد.

برای یک استخر "iscsi" یا "iscsi-direct"، حداقل XML مورد انتظار عنصر <host> با مشخصهٔ "name" است که آدرس IP یا نام میزبان مورد استفاده برای یافتن استخر (آدرس سرور iSCSI) را شرح می‌دهد. به صورت اختیاری، مشخصهٔ "port" نیز می‌تواند ارائه شود، گرچه مقدار پیش‌فرض آن 3260 خواهد بود. همچنین به صورت اختیاری، یک عنصر XML با نام <initiator> دارای مشخصهٔ "name" می‌تواند برای محدود کردن بیشتر جستجوی هدف iSCSI به یک initiator خاص برای استخرهای ذخیره‌سازی چندگانهٔ iSCSI (multi-iqn) ارائه شود.

find-pool-sources-as

نحو:

find-storage-pool-sources-as type [host] [port] [initiator]

به جای ارائهٔ فایل XML با نام srcSpec برای find-storage-pool-sources، از این گزینهٔ دستور استفاده کنید تا virsh فایل XML پرس‌وجو را با استفاده از آرگومان‌های اختیاری تولید کند. این دستور همان خروجی XML مربوط به find-storage-pool-sources را بازمی‌گرداند.

از host برای توصیف یک میزبان خاص برای ذخیره‌سازی تحت شبکه، مانند استخرهای از type مربوط به netfs، gluster و iscsi استفاده کنید.

از port برای محدود کردن بیشتر درگاه شبکه‌ای مورد استفاده برای اتصال استفاده کنید، در صورتی که پس‌زمینهٔ ذخیره‌سازی خاصی مانند iscsi به آن نیاز داشته باشد.

از initiator برای محدودتر کردن جستجوهای استخر از type مربوط به iscsi به initiatorهای هدف خاص استفاده کنید.

pool-autostart

نحو:

pool-autostart pool-or-uuid [--disable]

پیکربندی اینکه آیا pool باید هنگام بوت به طور خودکار شروع شود یا خیر..SS pool-build

دستور زبان:

pool-build pool-or-uuid [--overwrite] [--no-overwrite]

یک استخر (pool) مشخص‌شده را می‌سازد.

گزینه‌های --overwrite و --no-overwrite تنها می‌توانند برای pool-build روی یک استخر از نوع filesystem، disk یا logical استفاده شوند.

برای یک استخر سیستم‌فایل (file system)، اگر هیچ‌یک از پرچم‌ها مشخص نشده باشد، pool-build صرفاً دایرکتوری مسیر مقصد را ایجاد کرده و تلاشی برای اجرای mkfs روی دستگاه حجم مقصد نمی‌کند. اگر --no-overwrite مشخص شده باشد، بررسی می‌کند تا مشخص شود آیا از پیش سیستم‌فایلی روی دستگاه مقصد وجود دارد یا خیر؛ در صورت وجود، خطایی برمی‌گرداند و در صورت عدم وجود، از mkfs برای قالب‌بندی دستگاه مقصد استفاده می‌کند. اگر --overwrite مشخص شود، mkfs همواره اجرا شده و هر دادهٔ موجود روی دستگاه مقصد بدون قید و شرط بازنویسی می‌شود.

برای یک استخر دیسک (disk pool)، اگر هیچ‌کدام یا --no-overwrite مشخص شده باشد، pool-build پیش از اقدام به نوشتن برچسب (label) جدید روی دستگاه حجم مقصد، وجود سیستم‌فایل‌ها یا پارتیشن‌های فعلی را بررسی می‌کند. اگر دستگاه حجم مقصد از قبل دارای برچسب باشد، دستور با شکست مواجه می‌شود. اگر --overwrite مشخص شده باشد، هیچ بررسی‌ای پیش از نوشتن برچسب جدید روی دستگاه حجم مقصد انجام نخواهد شد. نوشتن برچسب از نوع قالب منبع استخر یا در صورت مشخص نشدن، از "dos" استفاده می‌کند.

برای یک استخر منطقی (logical pool)، اگر هیچ‌یک از آن‌ها یا --no-overwrite مشخص شده باشد، pool-build پیش از اقدام به مقداردهی اولیه و قالب‌بندی هر دستگاه برای استفاده توسط استخر منطقی، دستگاه‌های حجم مقصد را برای بررسی وجود سیستم‌فایل‌ها یا پارتیشن‌ها ارزیابی می‌کند. اگر هر یک از دستگاه‌های حجم مقصد از قبل برچسب داشته باشند، دستور با شکست مواجه خواهد شد. اگر --overwrite مشخص شده باشد، پیش از مقداردهی اولیه و قالب‌بندی هر دستگاه، هیچ بررسی‌ای روی دستگاه‌های حجم مقصد انجام نمی‌گیرد. پس از آن‌که تمام دستگاه‌های حجم مقصد به‌درستی از طریق pvcreate قالب‌بندی شدند، گروه حجم (volume group) با استفاده از تمام دستگاه‌ها ایجاد خواهد شد.

pool-create

دستور زبان:

pool-create file [--build] [[--overwrite] | [--no-overwrite]]

ایجاد و راه‌اندازی یک شیء استخر از file ورودی با ساختار XML.

گزینه‌های [--build] [[--overwrite] | [--no-overwrite]] پس از ایجاد، یک pool-build را اجرا می‌کنند تا نیاز به اجرای دستور تکمیلی بعدی برای ساخت استخر برطرف شود. پرچم‌های --overwrite و --no-overwrite از همان قواعد pool-build پیروی می‌کنند. اگر فقط --build ارائه شود، آن‌گاه pool-build بدون هیچ پرچمی فراخوانی می‌شود.

pool-create-as

دستور زبان:

pool-create-as name type
   [--source-host hostname] [--source-path path] [--source-dev path]
   [--source-name name] [--target path] [--source-format format]
   [--source-initiator initiator-iqn]
   [--auth-type authtype --auth-username username
   [--secret-usage usage | --secret-uuid uuid]]
   [--source-protocol-ver ver]
   [[--adapter-name name] | [--adapter-wwnn wwnn --adapter-wwpn wwpn]
   [--adapter-parent parent |
   --adapter-parent-wwnn parent_wwnn adapter-parent-wwpn parent_wwpn |
   --adapter-parent-fabric-wwn parent_fabric_wwn]]
   [--build] [[--overwrite] | [--no-overwrite]] [--print-xml]

ایجاد و راه‌اندازی یک شیء استخر با نام name بر اساس پارامترهای خام. اگر --print-xml مشخص شده باشد، خروجی XML شیء استخر بدون ایجاد استخر چاپ می‌شود. در غیر این صورت، استخر دارای type مشخص‌شده خواهد بود. هنگام استفاده از pool-create-as برای استخری از type با مقدار "disk"، پارتیشن‌های موجود پیدا شده در --source-dev path برای پر کردن استخر دیسک استفاده خواهند شد. بنابراین، پیشنهاد می‌شود از pool-define-as و pool-build به همراه --overwrite به منظور مقداردهی اولیهٔ صحیح استخر دیسک استفاده کنید.

گزینهٔ [--source-host hostname] نام میزبان منبع را برای استخرهایی که توسط فضای ذخیره‌سازی از یک کارگزار راه‌دور پشتیبانی می‌شوند مشخص می‌کند (انواع استخر netfs، iscsi، rbd، sheepdog، gluster).

گزینهٔ [--source-path path] مسیر دایرکتوری منبع را برای استخرهایی که مبتنی بر دایرکتوری هستند فراهم می‌کند (استخر از نوع dir).

گزینهٔ [--source-dev path] مسیر منبع را برای استخرهایی که مبتنی بر دستگاه‌های فیزیکی هستند فراهم می‌کند (انواع استخر fs، logical، disk، iscsi، zfs).

گزینهٔ [--source-name name] نام منبع را برای استخرهایی که از طریق یک عنصر نام‌گذاری‌شده ذخیره‌سازی می‌شوند مشخص می‌کند (انواع استخر logical، rbd، sheepdog، gluster).

گزینهٔ [--target path] مسیر مربوط به نگاشت استخر ذخیره‌سازی به درون سیستم‌فایل میزبان است.

گزینهٔ [--source-format format] اطلاعاتی دربارهٔ قالب استخر ارائه می‌دهد (انواع استخر fs، netfs، disk، logical).

گزینهٔ [--source-initiator initiator-iqn] شناسهٔ initiator iqn را برای اتصال iscsi استخر فراهم می‌کند (استخر از نوع iscsi-direct).

گزینه‌های [--auth-type authtype --auth-username username [--secret-usage usage | --secret-uuid uuid]] عناصر مورد نیاز برای ایجاد اعتبارنامه‌های احراز هویت را برای استخر ذخیره‌سازی فراهم می‌کنند. مقدار authtype می‌تواند chap برای استخرهای type از نوع iscsi یا ceph برای استخرهای type از نوع rbd باشد. یکی از مقادیر usage یا uuid کلید محرمانه (secret) می‌تواند مشخص شود، اما نه هر دوی آن‌ها.

گزینهٔ [--source-protocol-ver ver] شماره نسخهٔ پروتکل NFS مورد استفاده برای برقراری ارتباط با سرویس NFS کارگزار را از طریق گزینهٔ مونت nfs یعنی 'nfsvers=n' مشخص می‌کند. انتظار می‌رود مقدار ver یک عدد صحیح بدون علامت باشد.

گزینهٔ [--adapter-name name] نام آداپتور scsi_hostN را برای استفاده در استخر از نوع آداپتور scsi_host تعریف می‌کند.

گزینه‌های [--adapter-wwnn wwnn --adapter-wwpn wwpn [--adapter-parent parent | --adapter-parent-wwnn parent_wwnn adapter-parent-wwpn parent_wwpn | --adapter-parent-fabric-wwn parent_fabric_wwn]] شناسه‌های wwnn و wwpn مورد استفاده برای استخر نوع آداپتور fc_host را تعریف می‌کنند. به‌طور اختیاری دستگاه گره والد scsi_hostN را برای استفاده توسط vHBA می‌توان از طریق نام والد (parent name)، یا parent_wwnn و parent_wwpn، یا parent_fabric_wwn مشخص نمود. در صورت تغییر محیط سخت‌افزاری، نام والد ممکن است میان راه‌اندازی‌های مجدد تغییر کند؛ بنابراین تعیین parent_wwnn و parent_wwpn تضمین می‌کند که حتی در صورت تغییر دستگاه گره scsi_hostN، از همان HBA فیزیکی استفاده شود. استفاده از parent_fabric_wwn انعطاف‌پذیری بیشتری را جهت انتخاب یک HBA روی همان فابریک ذخیره‌سازی (storage fabric) برای تعریف استخر فراهم می‌کند.

گزینه‌های [--build] [[--overwrite] | [--no-overwrite]] پس از ایجاد، یک pool-build را اجرا می‌کنند تا نیاز به اجرای دستور تکمیلی بعدی برای ساخت استخر برطرف شود. پرچم‌های --overwrite و --no-overwrite از همان قواعد pool-build پیروی می‌کنند. اگر فقط --build ارائه شود، آن‌گاه pool-build بدون هیچ پرچمی فراخوانی می‌شود.

برای یک استخر "logical"، تنها ارائهٔ [--name] الزامی است. گزینهٔ [--source-name] در صورت ارائه باید با نام Volume Group مطابقت داشته باشد. در صورت ارائه نشدن، نامی با استفاده از [--name] تولید خواهد شد. در صورت ارائه شدن، مقدار [--target] نادیده گرفته شده و یک منبع مقصد با استفاده از [--source-name] (یا همان‌طور که از روی [--name] تولید شده) ایجاد می‌شود..SS pool-define

نحو:

pool-define file [--validate]

تعریف یک استخر ذخیره‌سازی مانای غیرفعال یا اصلاح یک استخر مانای موجود از طریق file با ساختار XML. به‌صورت اختیاری، قالب فایل XML ورودی می‌تواند با --validate در برابر یک شمای داخلی RNG اعتبارسنجی شود.

pool-define-as

نحو:

pool-define-as name type
   [--source-host hostname] [--source-path path] [--source-dev path]
   [*--source-name name*] [*--target path*] [*--source-format format*]
   [--source-initiator initiator-iqn]
   [*--auth-type authtype* *--auth-username username*
   [*--secret-usage usage* | *--secret-uuid uuid*]]
   [*--source-protocol-ver ver*]
   [[*--adapter-name name*] | [*--adapter-wwnn* *--adapter-wwpn*]
   [*--adapter-parent parent*]] [*--print-xml*]

ایجاد، اما راه‌اندازی نکردن، یک شیء استخر name از روی پارامترهای خام. اگر --print-xml مشخص شده باشد، ساختار XML شیء استخر بدون تعریف کردن استخر چاپ می‌شود. در غیر این صورت، استخر دارای type مشخص‌شده خواهد بود.

از همان آرگومان‌های pool-create-as استفاده کنید، به‌جز گزینه‌های --build، --overwrite و --no-overwrite.

pool-destroy

نحو:

pool-destroy pool-or-uuid

متوقف کردن (از بین بردن) یک شیء pool مشخص. Libvirt دیگر فضای ذخیره‌سازی توصیف‌شده توسط این شیء استخر را مدیریت نخواهد کرد، اما داده‌های خام موجود در استخر تغییری نمی‌کنند و بعداً می‌توان آن‌ها را با pool-create بازیابی کرد.

pool-delete

نحو:

pool-delete pool-or-uuid

از بین بردن منابع مصرف‌شده توسط یک شیء pool مشخص. این عملیات غیرقابل‌بازگشت است. شیء pool پس از اجرای این دستور همچنان وجود خواهد داشت و برای ایجاد حجم‌های ذخیره‌سازی جدید آماده خواهد بود.

pool-dumpxml

نحو:

pool-dumpxml [--inactive] [--xpath EXPRESSION] [--wrap] pool-or-uuid

اطلاعات XML دربارهٔ شیء pool را برمی‌گرداند. گزینهٔ --inactive به virsh می‌گوید به جای پیکربندی فعلی استخر، پیکربندی استخری را استخراج کند که در راه‌اندازی بعدی استخر استفاده خواهد شد.

اگر آرگومان --xpath یک عبارت XPath را ارائه دهد، روی خروجی XML ارزیابی شده و فقط گره‌های منطبق با آن چاپ خواهند شد. رفتار پیش‌فرض این است که هر گرهٔ منطبق به عنوان یک سند مستقل چاپ شود، اما برای سهولت در پردازش‌های بیشتر، آرگومان --wrap موجب می‌شود که گره‌های منطبق در یک گرهٔ ریشهٔ مشترک احاطه شوند..SS pool-edit

نحو:

pool-edit pool-or-uuid

ویرایش فایل پیکربندی XML برای یک استخر ذخیره‌سازی (storage pool).

این معادل است با:

virsh pool-dumpxml pool > pool.xml
vi pool.xml (or make changes with your other text editor)
virsh pool-define pool.xml

با این تفاوت که برخی بررسی‌های خطا را انجام می‌دهد.

ویرایشگر مورداستفاده می‌تواند از طریق متغیرهای محیطی $VISUAL یا $EDITOR تعیین شود، و پیش‌فرض آن vi است.

pool-info

نحو:

pool-info [--bytes] pool-or-uuid

اطلاعات پایه‌ای دربارهٔ شیء pool را برمی‌گرداند. اگر --bytes مشخص شده باشد، اندازه‌ها در اطلاعات پایه به واحدهای خوانا برای انسان تبدیل نمی‌شوند.

pool-list

نحو:

pool-list [--inactive] [--all]
   [--persistent] [--transient]
   [--autostart] [--no-autostart]
   [[--details] [--uuid]
   [--name] [<type>]

فهرست کردن اشیاء pool شناخته‌شده برای libvirt. به‌طور پیش‌فرض، تنها استخرهای فعال فهرست می‌شوند؛ --inactive فقط استخرهای غیرفعال را فهرست می‌کند، و --all تمام استخرها را فهرست می‌کند.

علاوه بر این، چندین دسته از پرچم‌های فیلتر کردن وجود دارد. --persistent برای فهرست کردن استخرهای پایا (persistent) است، --transient برای فهرست کردن استخرهای گذرا (transient) است. --autostart استخرهای دارای شروع خودکار را فهرست می‌کند، --no-autostart استخرهایی را که شروع خودکار آن‌ها غیرفعال است فهرست می‌کند. اگر --uuid مشخص شده باشد، تنها UUIDهای استخر چاپ می‌شوند. اگر --name مشخص شده باشد، تنها نام‌های استخر چاپ می‌شوند. اگر هر دو گزینهٔ --name و --uuid مشخص شده باشند، UUID و نام استخرها در کنار هم بدون هیچ سرآیندی چاپ می‌شوند. گزینهٔ --details با گزینه‌های --uuid و --name مانعة‌الجمع است.

همچنین ممکن است بخواهید استخرهایی با نوع‌های مشخص را با استفاده از type فهرست کنید؛ نوع‌های استخر باید با کاما از یکدیگر جدا شوند، مانند --type dir,disk. نوع‌های معتبر استخر شامل 'dir'، 'fs'، 'netfs'، 'logical'، 'disk'، 'iscsi'، 'scsi'، 'mpath'، 'rbd'، 'sheepdog'، 'gluster'، 'zfs'، 'vstorage' و 'iscsi-direct' هستند.

گزینهٔ --details به virsh دستور می‌دهد تا در صورت در دسترس بودن، اطلاعات مربوط به ماندگاری و ظرفیت استخر را نیز به صورت اضافه نمایش دهد.

نکته: هنگام برقراری ارتباط با سرورهای قدیمی‌تر، این دستور ناچار است از مجموعه‌ای از فراخوانی‌های API با شرایط رقابتی ذاتی (race condition) استفاده کند، که در آن اگر وضعیت یک استخر در حین جمع‌آوری فهرست بین فراخوانی‌ها تغییر کند، ممکن است آن استخر در فهرست آورده نشود یا بیش از یک بار ظاهر شود. سرورهای جدیدتر این مشکل را ندارند..SS pool-name

نحو:

pool-name uuid

uuid را به یک نام استخر تبدیل می‌کند.

pool-refresh

نحو:

pool-refresh pool-or-uuid

فهرست حجم‌های موجود در pool را تازه‌سازی می‌کند.

pool-start

نحو:

pool-start pool-or-uuid [--build] [[--overwrite] | [--no-overwrite]]

استخر ذخیره‌سازی pool را که پیش‌تر تعریف شده اما غیرفعال است، راه‌اندازی می‌کند.

گزینه‌های [--build] [[--overwrite] | [--no-overwrite]] پیش از pool-start یک pool-build را اجرا می‌کنند تا اطمینان حاصل شود محیط استخر در وضعیت مورد انتظار قرار دارد، به‌جای اینکه نیاز باشد پیش از راه‌اندازی، دستور ساخت به طور جداگانه اجرا شود. پرچم‌های --overwrite و --no-overwrite از همان قواعد pool-build پیروی می‌کنند. اگر تنها --build مشخص شود، pool-build بدون هیچ پرچمی فراخوانی می‌شود.

نکته: استخر ذخیره‌سازی که به منابع دوردست متکی است، مانند یک استخر "iscsi" یا یک استخر "scsi" مبتنی بر (v)HBA، ممکن است برای شناسایی تمامی حجم‌ها به چندین بار تازه‌سازی نیاز داشته باشد (به pool-refresh مراجعه کنید). دلیل این امر آن است که دستگاه‌های متناظر با حجم ممکن است هنگام راه‌اندازی اولیه استخر یا تلاش جاری برای تازه‌سازی، در سامانه فایل میزبان موجود نباشند. تعداد تلاش‌های مجدد برای تازه‌سازی به اتصال شبکه و مدت زمانی که میزبان برای ارائه دستگاه‌های متناظر نیاز دارد وابسته است.

pool-undefine

نحو:

pool-undefine pool-or-uuid

پیکربندی مربوط به یک pool غیرفعال را حذف تعریف می‌کند.

pool-uuid

نحو:

pool-uuid pool

شناسه UUID مربوط به pool نام‌برده را بازمی‌گرداند..SS pool-event

نحو:

pool-event {[pool] event [--loop] [--timeout seconds] [--timestamp] | --list}

برای رخ دادن دسته‌ای از رویدادهای استخر ذخیره‌سازی منتظر می‌ماند و جزئیات مناسب رویدادها را هنگام وقوع چاپ می‌کند. رویدادها می‌توانند به طور اختیاری بر اساس pool فیلتر شوند. استفاده از --list به عنوان تنها آرگومان، فهرستی از مقادیر ممکن event را که توسط این کلاینت شناخته شده است ارائه می‌دهد، اگرچه ممکن است اتصال اجازه ثبت‌نام برای همه این رویدادها را ندهد.

به‌طور پیش‌فرض، این دستور تک‌مرحله‌ای (one-shot) است و با وقوع یک رویداد وضعیت موفقیت‌آمیز بازمی‌گرداند؛ می‌توانید برای خروج فوری SIGINT (معمولاً از طریق Ctrl-C) ارسال کنید. اگر --timeout مشخص شده باشد، دستور پس از سپری شدن seconds ثانیه از انتظار برای رویدادها دست می‌کشد. با --loop، دستور همه رویدادها را تا پایان مهلت زمانی یا فشردن کلید وقفه چاپ می‌کند.

هنگامی که --timestamp استفاده شود، یک برچسب زمانی خوانا برای انسان پیش از رویداد چاپ خواهد شد.

vol-create

نحو:

vol-create pool-or-uuid FILE [--prealloc-metadata] [--validate]

یک حجم از یک <file> نوع XML ایجاد می‌کند.

pool-or-uuid نام یا UUID استخر ذخیره‌سازی برای ایجاد حجم در آن است.

FILE همان <file> با فرمت XML حاوی تعریف حجم است. یک روش آسان برای ایجاد <file> نوع XML، استفاده از دستور vol-dumpxml برای دریافت تعریف یک حجم از پیش موجود است.

[--prealloc-metadata] فراداده را پیش‌تخصیص می‌دهد (برای ایمیج‌های qcow2 که از تخصیص کامل پشتیبانی نمی‌کنند). این گزینه یک فایل ایمیج تنک (sparse) همراه با فراداده ایجاد می‌کند، که منجر به عملکرد بالاتر نسبت به ایمیج‌های بدون پیش‌تخصیص و استفاده اولیه از فضای دیسک تنها کمی بیشتر می‌شود.

اگر --validate مشخص شده باشد، قالب سند XML را در برابر یک شِمای داخلی RNG اعتبارسنجی می‌کند.

مثال:

virsh vol-dumpxml --pool storagepool1 appvolume1 > newvolume.xml
vi newvolume.xml (or make changes with your other text editor)
virsh vol-create differentstoragepool newvolume.xml

vol-create-from

نحو:

vol-create-from pool-or-uuid FILE vol-name-or-key-or-path
   [--inputpool pool-or-uuid]  [--prealloc-metadata] [--reflink] [--validate]

ایجاد یک حجم، با استفاده از یک حجم دیگر به عنوان ورودی.

pool-or-uuid نام یا UUID استخر ذخیره‌سازی برای ایجاد حجم در آن است.

FILE همان <file> با فرمت XML شامل تعریف حجم است.

vol-name-or-key-or-path نام، کلید یا مسیر حجم مبدأ است.

--inputpool pool-or-uuid نام یا UUID استخر ذخیره‌سازی است که حجم مبدأ در آن قرار دارد.

[--prealloc-metadata] فراداده را پیش‌تخصیص می‌دهد (برای ایمیج‌های qcow2 که از تخصیص کامل پشتیبانی نمی‌کنند). این گزینه یک فایل ایمیج تنک (sparse) با فراداده ایجاد می‌کند، که منجر به کارایی بالاتر در مقایسه با ایمیج‌های فاقد پیش‌تخصیص و تنها مصرف اولیه اندکی بیشتر از فضای دیسک می‌شود.

هنگامی که --reflink مشخص شود، یک کپی سبک COW انجام می‌دهد که در آن بلوک‌های داده تنها هنگام تغییر کپی می‌شوند. در صورتی که این کار ممکن نباشد، عملیات کپی با شکست مواجه می‌شود.

اگر --validate مشخص شده باشد، قالب سند XML را در برابر یک شِمای داخلی RNG اعتبارسنجی می‌کند..SS vol-create-as

ساختار دستوری:

vol-create-as pool-or-uuid name capacity [--allocation size] [--format string]
   [--backing-vol vol-name-or-key-or-path]
   [--backing-vol-format string] [--prealloc-metadata] [--print-xml]

یک حجم را از مجموعه‌ای از آرگومان‌ها ایجاد می‌کند، مگر اینکه --print-xml مشخص شده باشد که در این صورت فقط XML شیء حجم بدون ایجاد واقعی شیء چاپ می‌شود.

pool-or-uuid نام یا UUID استخر ذخیره‌سازی برای ایجاد حجم در آن است.

name نام حجم جدید است. برای یک استخر دیسک (disk pool)، این نام باید با نام پارتیشن تعیین‌شده بر اساس مسیر دستگاه مبدأ استخر و پارتیشن در دسترس بعدی مطابقت داشته باشد. برای مثال، اگر مسیر دستگاه مبدأ /dev/sdb باشد و هیچ پارتیشنی روی دیسک وجود نداشته باشد، نام باید sdb1 باشد و نام بعدی sdb2 و به همین ترتیب خواهد بود.

capacity اندازهٔ حجمی است که باید ایجاد شود، به‌صورت یک عدد صحیح مقیاس‌دار (به بخش NOTES در بالا مراجعه کنید)، که در صورت نبود پسوند، پیش‌فرض بایت خواهد بود.

--allocation size اندازهٔ اولیه برای تخصیص در حجم است، که آن هم به‌صورت یک عدد صحیح مقیاس‌دار با پیش‌فرض بایت می‌باشد.

--format string در استخرهای ذخیره‌سازی مبتنی بر فایل برای مشخص کردن قالب فایل حجم استفاده می‌شود؛ raw، bochs، qcow، qcow2، vmdk، qed. از extended برای استخرهای ذخیره‌سازی دیسک به‌منظور ایجاد یک پارتیشن توسعه‌یافته (extended) استفاده کنید (سایر مقادیر بررسی صحت می‌شوند اما هنگام راه‌اندازی مجدد libvirtd یا نوسازی استخر حفظ نخواهند شد).

--backing-vol vol-name-or-key-or-path حجم پشتیبان مبدأ است که در صورت تهیهٔ اسنپ‌شات از یک حجم موجود استفاده می‌شود.

--backing-vol-format string قالب حجم پشتیبان اسنپ‌شات است؛ raw، bochs، qcow، qcow2، qed، vmdk، host_device. هرچند این موارد برای استخرهای ذخیره‌سازی مبتنی بر فایل در نظر گرفته شده‌اند.

[--prealloc-metadata] فراداده را از پیش تخصیص می‌دهد (برای ایمیج‌های qcow2 که از تخصیص کامل پشتیبانی نمی‌کنند). این گزینه یک فایل ایمیج متخلخل (sparse) همراه با فراداده ایجاد می‌کند، که در مقایسه با ایمیج‌های بدون پیش‌تخصیص، به عملکرد بالاتر و تنها مصرف اولیهٔ کمی بیشتر از فضای دیسک منجر می‌شود.

vol-clone

ساختار دستوری:

vol-clone vol-name-or-key-or-path name
   [--pool pool-or-uuid] [--prealloc-metadata] [--reflink] [--print-xml]

یک حجم موجود را درون استخر والد شبیه‌سازی (clone) می‌کند. نسخه‌ای با قدرت کمتر اما با تایپ آسان‌تر از دستور vol-create-from است.

vol-name-or-key-or-path نام، کلید یا مسیر حجم مبدأ است.

name نام حجم جدید است.

--pool pool-or-uuid نام یا UUID استخر ذخیره‌سازی است که شامل حجم مبدأ بوده و حجم جدید را نیز دربر خواهد گرفت. اگر به جای کلید یا مسیر، نام حجم مبدأ ارائه شود، مشخص کردن استخر برای یافتن حجمی که باید کلون شود ضروری است؛ در غیر این صورت، از اولین حجمی که بر اساس کلید یا مسیر پیدا شود استفاده خواهد شد.

[--prealloc-metadata] فراداده را از پیش تخصیص می‌دهد (برای ایمیج‌های qcow2 که از تخصیص کامل پشتیبانی نمی‌کنند). این گزینه یک فایل ایمیج متخلخل (sparse) همراه با فراداده ایجاد می‌کند، که در مقایسه با ایمیج‌های بدون پیش‌تخصیص، به عملکرد بالاتر و تنها مصرف اولیهٔ کمی بیشتر از فضای دیسک منجر می‌شود.

هنگامی که --reflink مشخص شده باشد، یک رونوشت سبک COW انجام می‌دهد، که در آن بلوک‌های داده تنها در صورت تغییر رونویسی می‌شوند. اگر این امر امکان‌پذیر نباشد، عملیات کپی ناموفق خواهد بود.

اگر --print-xml مشخص شده باشد، در عوض ساختار XML مورد استفاده برای کلون کردن حجم در خروجی چاپ می‌شود..SS vol-delete

نحو:

vol-delete vol-name-or-key-or-path [--pool pool-or-uuid] [--delete-snapshots]

یک حجم داده‌شده را حذف می‌کند.

آرگومان vol-name-or-key-or-path نام حجم، کلید یا مسیر حجمی است که باید حذف شود.

گزینه [--pool pool-or-uuid] نام یا UUID استخر ذخیره‌سازی است که حجم در آن قرار دارد. اگر به‌جای کلید یا مسیر، نام حجم ارائه شود، ارائهٔ استخر برای یافتن حجم جهت حذف ضروری است؛ در غیر این صورت، از نخستین حجمی که با کلید یا مسیر یافت شود استفاده خواهد شد.

پرچم --delete-snapshots مشخص می‌کند که هرگونه اسنپ‌شات مرتبط با حجم ذخیره‌سازی نیز باید حذف شود. همه درایورهای ذخیره‌سازی از این گزینه پشتیبانی نمی‌کنند؛ در حال حاضر تنها rbd پشتیبانی می‌شود.

vol-upload

نحو:

vol-upload vol-name-or-key-or-path local-file
   [--pool pool-or-uuid] [--offset bytes]
   [--length bytes] [--sparse]

محتویات local-file را روی یک حجم ذخیره‌سازی بارگذاری می‌کند.

آرگومان vol-name-or-key-or-path نام، کلید یا مسیر حجمی است که local-file در آن بارگذاری خواهد شد.

گزینه --pool pool-or-uuid نام یا UUID استخر ذخیره‌سازی است که حجم در آن قرار دارد. اگر به‌جای کلید یا مسیر، نام حجم ارائه شود، ارائهٔ استخر برای یافتن حجمی که باید در آن بارگذاری انجام شود ضروری است؛ در غیر این صورت، نخستین حجمی که با کلید یا مسیر پیدا شود استفاده خواهد شد.

گزینه --offset موقعیتی در حجم ذخیره‌سازی است که نوشتن داده‌ها باید از آنجا آغاز شود. این مقدار باید ۰ یا بزرگ‌تر باشد.

گزینه --length کران بالای مقدار داده‌ای است که باید بارگذاری شود. مقدار منفی به‌صورت یک مقدار بدون علامت unsigned long long تفسیر می‌شود تا اساساً همه‌چیز را از افست تا انتهای حجم در بر بگیرد.

اگر --sparse مشخص شده باشد، این دستور پراکندگی (حالت sparse) حجم را حفظ خواهد کرد.

اگر حجم local-file از مقدار مشخص‌شده برای length بیشتر باشد، خطایی رخ خواهد داد.

برای جزئیات مربوط به تغییرات احتمالی حجم و استخر هدف در نتیجهٔ نوسازی (refresh) استخر هنگام اقدام به بارگذاری، به توضیحات مربوط به API رابط virStorageVolUpload در libvirt مراجعه کنید.

vol-download

نحو:

vol-download vol-name-or-key-or-path local-file
   [--pool pool-or-uuid] [--offset bytes] [--length bytes]
   [--sparse]

محتویات یک حجم ذخیره‌سازی را در local-file بارگیری می‌کند.

آرگومان vol-name-or-key-or-path نام، کلید یا مسیر حجمی است که باید در local-file بارگیری شود.

گزینه --pool pool-or-uuid نام یا UUID استخر ذخیره‌سازی است که حجم در آن قرار دارد. اگر به‌جای کلید یا مسیر، نام حجم ارائه شود، ارائهٔ استخر برای یافتن حجم جهت بارگیری داده‌ها ضروری است؛ در غیر این صورت، نخستین حجمی که با کلید یا مسیر پیدا شود استفاده خواهد شد.

گزینه --offset موقعیتی در حجم ذخیره‌سازی است که خواندن داده‌ها باید از آنجا آغاز شود. این مقدار باید ۰ یا بزرگ‌تر باشد.

گزینه --length کران بالای مقدار داده‌ای است که باید بارگیری شود. مقدار منفی به‌صورت یک مقدار بدون علامت unsigned long long تفسیر می‌شود تا اساساً همه‌چیز را از افست تا انتهای حجم در بر بگیرد.

اگر --sparse مشخص شده باشد، این دستور پراکندگی (حالت sparse) حجم را حفظ خواهد کرد..SS vol-wipe

ساختار:

vol-wipe vol-name-or-key-or-path [--pool pool-or-uuid] [--algorithm algorithm]

پاک‌سازی کامل یک حجم ذخیره‌سازی (volume) و حصول اطمینان از اینکه داده‌های پیشین روی آن برای خواندن‌های آتی غیرقابل‌دسترس هستند.

vol-name-or-key-or-path نام، کلید یا مسیر حجمی است که باید پاک‌سازی شود. امکان انتخاب الگوریتم‌های پاک‌سازی مختلف به جای بازنویسی حجم با صفر وجود دارد.

--pool pool-or-uuid نام یا UUID استخر ذخیره‌سازی (storage pool) است که حجم در آن قرار دارد. اگر به جای کلید یا مسیر، نام حجم مشخص شود، ارائهٔ استخر برای یافتن حجمی که باید پاک‌سازی شود ضروری است؛ در غیر این صورت، نخستین حجم یافت‌شده بر اساس کلید یا مسیر استفاده خواهد شد.

برای تعیین الگوریتم مورد استفاده در پاک‌سازی، از سوئیچ --algorithm با انتخاب از فهرست الگوریتم‌های زیر استفاده کنید.

الگوریتم‌های پشتیبانی‌شده

نکته: باینری scrub برای مدیریت الگوریتم‌های 'nnsa'، 'dod'، 'bsi'، 'gutmann'، 'schneier'، 'pfitzner7' و 'pfitzner33' استفاده خواهد شد. در دسترس بودن این الگوریتم‌ها ممکن است توسط نسخهٔ باینری scrub نصب‌شده روی میزبان محدود باشد. الگوریتم 'zero' صفرها را روی کل حجم می‌نویسد. برای برخی حجم‌ها، مانند حجم‌های sparse یا rbd، این کار ممکن است منجر به پر شدن کامل حجم با صفرها شود و طوری به نظر برسد که گویی حجم کاملاً پر شده است. به عنوان جایگزین، الگوریتم 'trim' تمام داده‌های یک حجم را بازنویسی نمی‌کند، بلکه انتظار دارد که درایور ذخیره‌سازی بتواند تمام بایت‌های درون حجم را دور بریزد (discard). نحوهٔ مدیریت چگونگی انجام دورریزی بر عهدهٔ درایور ذخیره‌سازی است. همهٔ درایورهای ذخیره‌سازی یا انواع حجم‌ها از 'trim' پشتیبانی نمی‌کنند.

vol-dumpxml

ساختار:

vol-dumpxml [--pool pool-or-uuid] [--xpath EXPRESSION] [--wrap]
            vol-name-or-key-or-path

خروجی دادن اطلاعات حجم در قالب یک رونوشت XML روی stdout.

vol-name-or-key-or-path نام، کلید یا مسیر حجمی است که باید XML آن در خروجی چاپ شود.

--pool pool-or-uuid نام یا UUID استخر ذخیره‌سازی است که حجم در آن قرار دارد. اگر به جای کلید یا مسیر، نام حجم ارائه شود، مشخص کردن استخر برای یافتن حجم ضروری است؛ در غیر این صورت، نخستین حجم یافت‌شده بر اساس کلید یا مسیر استفاده خواهد شد.

اگر آرگومان --xpath یک عبارت XPath ارائه دهد، بر روی XML خروجی ارزیابی شده و تنها گره‌های منطبق چاپ خواهند شد. رفتار پیش‌فرض این است که هر گرهٔ منطبق به عنوان یک سند مستقل چاپ شود؛ با این حال، جهت سهولت در پردازش‌های بعدی، آرگومان --wrap باعث می‌شود که گره‌های منطبق درون یک گرهٔ ریشه (root node) مشترک قرار گیرند..SS vol-info

ساختار:

vol-info vol-name-or-key-or-path [--pool pool-or-uuid] [--bytes] [--physical]

اطلاعات پایه‌ای درباره حجم ذخیره‌سازی مشخص‌شده را بازمی‌گرداند.

vol-name-or-key-or-path نام، کلید یا مسیر حجمی است که اطلاعات آن بازگردانده می‌شود.

--pool pool-or-uuid نام یا UUID استخر ذخیره‌سازی است که حجم در آن قرار دارد. اگر به جای کلید یا مسیر، نام حجم ارائه شود، ارائه استخر برای یافتن حجم ضروری است؛ در غیر این صورت، اولین حجمی که با کلید یا مسیر پیدا شود استفاده خواهد شد.

اگر --bytes مشخص شود، اندازه‌ها به واحدهای خوانا برای انسان تبدیل نمی‌شوند.

اگر --physical مشخص شود، اندازه فیزیکی میزبان به‌جای مقدار تخصیص (allocation) بازگردانده و نمایش داده می‌شود. مقدار فیزیکی برای برخی از انواع فایل‌ها، مانند qcow2، ممکن است مقدار متفاوتی (بزرگ‌تر) نسبت به آنچه برای تخصیص نشان داده شده است داشته باشد. علاوه بر این، فایل‌های کم‌پشت (sparse) مقادیر فیزیکی و تخصیص متفاوتی خواهند داشت.

vol-list

ساختار:

vol-list [--pool pool-or-uuid] [--details]

فهرست حجم‌های موجود در استخر ذخیره‌سازی مشخص‌شده را بازمی‌گرداند.

--pool pool-or-uuid نام یا UUID استخر ذخیره‌سازی است.

گزینه --details به virsh دستور می‌دهد که در صورت موجود بودن، اطلاعات مربوط به نوع و ظرفیت حجم را نیز نمایش دهد.

vol-pool

ساختار:

vol-pool vol-key-or-path [--uuid]

نام استخر یا UUID مربوط به یک حجم مشخص را بازمی‌گرداند. به‌طور پیش‌فرض، نام استخر بازگردانده می‌شود.

vol-key-or-path کلید یا مسیر حجمی است که باید اطلاعات استخر آن بازگردانده شود.

اگر گزینه --uuid داده شود، به‌جای آن UUID استخر بازگردانده می‌شود.

vol-path

ساختار:

vol-path vol-name-or-key [--pool pool-or-uuid]

مسیر یک حجم مشخص را بازمی‌گرداند.

vol-name-or-key نام یا کلید حجمی است که مسیر آن بازگردانده می‌شود.

--pool pool-or-uuid نام یا UUID استخر ذخیره‌سازی است که حجم در آن قرار دارد. اگر به جای کلید، نام حجم ارائه شود، ارائه استخر برای یافتن حجم ضروری است؛ در غیر این صورت، اولین حجمی که با کلید پیدا شود استفاده خواهد شد..SS vol-name

ساختار:

vol-name vol-key-or-path

نام یک حجم مشخص را برمی‌گرداند.

پارامتر vol-key-or-path کلید یا مسیر حجمی است که نام آن باید بازگردانده شود.

vol-key

ساختار:

vol-key vol-name-or-path [--pool pool-or-uuid]

کلید حجم را برای یک حجم مشخص برمی‌گرداند.

پارامتر vol-name-or-path نام یا مسیر حجمی است که کلید آن باید بازگردانده شود.

گزینهٔ --pool pool-or-uuid نام یا UUID مخزن ذخیره‌سازی (storage pool) است که حجم در آن قرار دارد. اگر به جای مسیر، نام حجم ارائه شده باشد، مشخص کردن مخزن جهت یافتن حجم مورد نظر الزامی است؛ در غیر این صورت، از اولین حجمی که از طریق مسیر پیدا شود استفاده خواهد شد.

vol-resize

ساختار:

vol-resize vol-name-or-path capacity [--pool pool-or-uuid] [--allocate] [--delta] [--shrink]

ظرفیت حجم داده‌شده را بر حسب بایت تغییر اندازه می‌دهد.

پارامتر vol-name-or-key-or-path نام، کلید یا مسیر حجمی است که اندازهٔ آن تغییر داده می‌شود.

پارامتر capacity یک عدد صحیح مقیاس‌بندی‌شده است (به بخش NOTES در بالا مراجعه کنید) که در صورت نداشتن پسوند، پیش‌فرض آن بایت است.

گزینهٔ --pool pool-or-uuid نام یا UUID مخزن ذخیره‌سازی است که حجم در آن قرار دارد. اگر نام حجم به‌جای کلید یا مسیر داده شود، تعیین مخزن برای یافتن حجم مورد نظر ضروری است؛ در غیر این صورت، نخستین حجمِ یافت‌شده بر اساس کلید یا مسیر استفاده خواهد شد.

ظرفیت جدید (capacity) ممکن است پراکنده (sparse) باشد مگر اینکه --allocate مشخص شده باشد.

به‌طور معمول، capacity اندازهٔ جدید است، اما در صورت حضور --delta، این مقدار به اندازهٔ فعلی افزوده می‌شود.

تلاش‌ها برای کوچک کردن حجم ناموفق خواهند بود مگر اینکه --shrink مشخص شده باشد. مقدار capacity نمی‌تواند منفی باشد مگر اینکه --shrink ارائه شود، هرچند که درج علامت منفی الزامی نیست.

این دستور تنها برای حجم‌های ذخیره‌سازی که توسط یک مهمان فعال استفاده نمی‌شوند امن است؛ همچنین برای تغییر اندازهٔ زنده به blockresize مراجعه کنید.

secret-dumpxml

ساختار:

secret-dumpxml [--xpath EXPRESSION] [--wrap] secret

مشخصات secret (تعیین‌شده توسط UUID آن) را به‌صورت خروجی XML در stdout چاپ می‌کند.

اگر آرگومان --xpath یک عبارت XPath ارائه دهد، در برابر خروجی XML ارزیابی شده و تنها گره‌های منطبق چاپ خواهند شد. رفتار پیش‌فرض این است که هر گرهٔ منطبق به‌صورت یک سند مستقل چاپ شود؛ با این حال، جهت سهولت در پردازش‌های بیشتر، آرگومان --wrap باعث می‌شود گره‌های منطبق درون یک گرهٔ ریشهٔ مشترک قرار گیرند.

secret-event

ساختار:

secret-event {[secret] event [--loop] [--timeout seconds] [--timestamp] | --list}

منتظر وقوع دسته‌ای از رویدادهای راز می‌ماند و جزئیات مربوط به رویدادها را هنگام رخ دادن چاپ می‌کند. رویدادها را می‌توان به‌صورت اختیاری با secret فیلتر کرد. استفاده از --list به‌عنوان تنها آرگومان، فهرستی از مقادیر ممکن event را که برای این کلاینت شناخته‌شده است ارائه می‌دهد، اگرچه ممکن است اتصال اجازهٔ ثبت‌نام برای همهٔ این رویدادها را ندهد.

به‌طور پیش‌فرض، این دستور یک‌باره است و پس از رخ دادن یک رویداد وضعیت موفقیت‌آمیز برمی‌گرداند؛ می‌توانید با ارسال SIGINT (معمولاً از طریق Ctrl-C) فوراً از آن خارج شوید. اگر --timeout مشخص شده باشد، دستور پس از سپری شدن seconds ثانیه از انتظار برای رویدادها دست می‌کشد. با --loop، دستور تمام رویدادها را تا زمان پایان مهلت یا دریافت کلید وقفه چاپ می‌کند.

هنگام استفاده از --timestamp، یک برچسب زمانی خوانا برای انسان پیش از رویداد چاپ خواهد شد.

secret-set-value

ساختار:

secret-set-value secret (--file filename [--plain] | --interactive | base64)

مقدار مرتبط با secret (مشخص‌شده توسط UUID آن) را روی مقدار کُدگذاری‌شده با Base64 در base64 یا محتویات کُدگذاری‌شده با Base64 فایلی به نام filename تنظیم می‌کند. استفاده از پرچم --plain همراه با --file این امکان را فراهم می‌کند که از محتوای فایل مستقیماً به‌عنوان مقدار راز استفاده شود.

اگر پرچم --interactive به کار رود، مقدار راز مانند یک گذرواژه از ترمینال خوانده می‌شود.

توجه داشته باشید که گزینه‌های --file، --interactive و base64 مانعة‌الجمع هستند.

ارسال رازها از طریق گزینهٔ base64 در خط فرمان ناامن (INSECURE) بوده و منسوخ شده است. به‌جای آن از گزینهٔ --file استفاده کنید..SS secret-get-value

نحو:

secret-get-value [--plain] secret

مقدار مرتبط با secret (مشخص‌شده با UUID آن) را به‌صورت کدگذاری‌شده با Base64 در خروجی استاندارد (stdout) چاپ می‌کند.

اگر پرچم --plain استفاده شود، مقدار با Base64 کدگذاری نشده و به‌صورت خام چاپ می‌شود. توجه داشته باشید مگر اینکه virsh در حالت بی‌صدا (virsh -q) اجرا شده باشد، یک خط جدید در انتهای دستور چاپ می‌کند. این خط جدید بخشی از secret نیست.

secret-undefine

نحو:

secret-undefine secret

یک secret (مشخص‌شده با UUID آن) را به همراه مقدار مرتبط، در صورت وجود، حذف می‌کند.

secret-list

نحو:

secret-list [--ephemeral] [--no-ephemeral]
   [--private] [--no-private]

فهرست رازها (secrets) را بازمی‌گرداند. همچنین می‌توانید رازهای بازگردانده‌شده را با --ephemeral برای فهرست کردن موارد گذرا، --no-ephemeral برای موارد غیرگذرا، --private برای موارد خصوصی، و --no-private برای فهرست کردن موارد غیرخصوصی پالایش کنید.

snapshot-create

نحو:

snapshot-create domain [xmlfile] {[--redefine [--current]] |
   [--no-metadata] [--halt] [--disk-only] [--reuse-external]
   [--quiesce] [--atomic] [--live]} [--validate]

یک اسنپ‌شات برای دامنه domain با ویژگی‌های مشخص‌شده در xmlfile ایجاد می‌کند. در صورت تمایل، گزینه --validate را می‌توان برای اعتبارسنجی قالب فایل XML ورودی در برابر شِمای داخلی RNG ارسال کرد (مشابه استفاده از ابزار virt-xml-validate(1)). به‌طور معمول، تنها ویژگی‌های قابل تنظیم برای یک اسنپ‌شات دامنه، عناصر <name> و <description> هستند، و همچنین <disks> در صورتی که --disk-only مشخص شده باشد؛ بقیه فیلدها نادیده گرفته شده و به‌طور خودکار توسط libvirt مقداردهی می‌شوند. اگر xmlfile کاملاً حذف شود، libvirt برای همه فیلدها مقداری را انتخاب خواهد کرد. اسنپ‌شات جدید به عنوان اسنپ‌شات جاری در نظر گرفته خواهد شد، همان‌طور که توسط snapshot-current فهرست می‌شود.

اگر --halt مشخص شود، دامنه پس از ایجاد اسنپ‌شات در وضعیتی غیرفعال رها خواهد شد.

اگر --disk-only مشخص شود، اسنپ‌شات فقط شامل محتوای دیسک خواهد بود و نه اسنپ‌شات معمول سیستم کامل به همراه وضعیت ماشین مجازی. ثبت اسنپ‌شات‌های دیسک سریع‌تر از اسنپ‌شات‌های سیستم کامل انجام می‌شود، اما بازگردانی به یک اسنپ‌شات دیسک ممکن است نیازمند fsck یا بازپخش ژورنال باشد، زیرا این حالت مشابه وضعیت دیسک در لحظه قطع ناگهانی کابل برق است؛ و ترکیب --halt و --disk-only هرگونه داده‌ای را که در آن لحظه روی دیسک تخلیه نشده باشد از بین می‌برد.

اگر --redefine مشخص شود، تمامی عناصر XML تولیدشده توسط snapshot-dumpxml معتبر خواهند بود؛ این گزینه می‌تواند برای مهاجرت سلسله‌مراتب اسنپ‌شات از یک ماشین به ماشین دیگر، بازسازی سلسله‌مراتب برای دامنه‌های گذرایی که بسته شده و بعداً با همان نام و UUID دوباره ایجاد می‌شوند، یا اعمال تغییرات جزئی در فراداده اسنپ‌شات (مانند جنبه‌های وابسته به میزبان در XML دامنه که درون اسنپ‌شات گنجانده شده است) استفاده شود. هنگام استفاده از این پرچم، آرگومان xmlfile الزامی است و اسنپ‌شات جاری دامنه تغییر نخواهد کرد مگر اینکه پرچم --current نیز داده شده باشد.

اگر --no-metadata مشخص شود، داده‌های اسنپ‌شات ایجاد می‌شوند اما هرگونه فراداده بلافاصله دور انداخته می‌شود (یعنی libvirt با اسنپ‌شات به عنوان اسنپ‌شات جاری رفتار نمی‌کند و نمی‌تواند به آن بازگردانی کند، مگر اینکه بعداً از --redefine برای معرفی مجدد فراداده به libvirt استفاده شود).

اگر --reuse-external مشخص شود و XML اسنپ‌شات یک اسنپ‌شات خارجی با مقصد یک فایل موجود را درخواست کند، آنگاه مقصد باید از پیش موجود بوده و با قالب و فراداده صحیح ایجاد شده باشد. سپس فایل مجدداً استفاده می‌شود؛ در غیر این صورت، برای جلوگیری از دست رفتن محتویات فایل‌های موجود، درخواست اسنپ‌شات رد خواهد شد.

اگر --quiesce مشخص شود، libvirt تلاش خواهد کرد از عامل مهمان (guest agent) برای منجمد کردن و آزادسازی سیستم‌های فایل متصل‌شده دامنه استفاده کند. با این حال، اگر دامنه فاقد عامل مهمان باشد، ایجاد اسنپ‌شات شکست خواهد خورد. در حال حاضر، این مورد نیازمند ارسال --disk-only نیز می‌باشد.

اگر --atomic مشخص شود، libvirt تضمین می‌کند که اسنپ‌شات یا کاملاً موفقیت‌آمیز باشد یا بدون هیچ تغییری شکست بخورد؛ همه هایپروایزرها از این قابلیت پشتیبانی نمی‌کنند. اگر این پرچم مشخص نشود، برخی هایپروایزرها ممکن است پس از انجام ناقص عملیات با خطا مواجه شوند، و باید از dumpxml برای بررسی رخ دادن هرگونه تغییر ناقص استفاده شود.

اگر --live مشخص شود، libvirt اسنپ‌شات را در حین اجرای ماشین مهمان تهیه می‌کند. هم اسنپ‌شات دیسک و هم اسنپ‌شات حافظه دامنه ثبت می‌شوند. این کار اندازه ایمیج حافظه اسنپ‌شات خارجی را افزایش می‌دهد. در حال حاضر این قابلیت فقط برای اسنپ‌شات‌های خارجی سیستم کامل پشتیبانی می‌شود.

وجود فراداده اسنپ‌شات از تلاش‌ها برای undefine کردن یک مهمان ماندگار جلوگیری می‌کند. با این حال، برای دامنه‌های گذرا، زمانی که اجرای دامنه متوقف می‌شود (خواه با دستوری مانند destroy یا با کنش داخلی ماشین مهمان)، فراداده اسنپ‌شات بدون هشدار از بین می‌رود.

در حال حاضر، ایجاد اسنپ‌شات در دامنه‌ای که دارای چک‌پوینت (checkpoint) است امکان‌پذیر نیست، هرچند این محدودیت در انتشار‌های آینده برداشته خواهد شد..SS snapshot-create-as

ساختار دستوری:

snapshot-create-as domain {[--print-xml] [--no-metadata]
   [--halt] [--reuse-external]} [name]
   [description] [--disk-only [--quiesce]] [--atomic] [--validate]
   [[--live] [--memspec memspec]] [--diskspec] diskspec]...

یک اسنپ‌شات برای دامنهٔ domain با <name> و <description> مشخص‌شده ایجاد می‌کند؛ اگر هرکدام از این مقادیر حذف شوند، libvirt مقداری را برمی‌گزیند. اگر --print-xml مشخص شده باشد، به‌جای ایجاد واقعی اسنپ‌شات، XML مناسب برای snapshot-create در خروجی نمایش داده می‌شود. در غیر این صورت، چنانچه --halt مشخص شود، دامنه پس از ایجاد اسنپ‌شات در وضعیتی غیرفعال باقی می‌ماند، و اگر --disk-only مشخص شده باشد، اسنپ‌شات وضعیت ماشین مجازی (vm state) را در بر نخواهد گرفت.

گزینهٔ --memspec می‌تواند برای کنترل داخلی یا خارجی بودن اسنپ‌شات کامل سیستم به کار رود. پرچم --memspec اجباری است و پس از آن یک memspec به شکل [file=]name[,snapshot=type] می‌آید، که در آن type می‌تواند no، internal یا external باشد. برای گنجاندن یک کامای تحت‌اللفظی در file=name، آن را با یک کامای دوم گریزدهی (escape) کنید. --memspec نمی‌تواند همراه با --disk-only استفاده شود.

گزینهٔ --diskspec می‌تواند برای کنترل نحوهٔ ایجاد فایل‌های خارجی توسط --disk-only و اسنپ‌شات‌های خارجی کامل سیستم به کار رود. این گزینه با توجه به تعداد عناصر <disk> در xml دامنه می‌تواند چندین بار تکرار شود. هر <diskspec> به صورت disk[,snapshot=type][,driver=type][,stype=type][,file=name] است. برای دیسک‌هایی که توسط دستگاه‌های بلوکی (block devices) پشتیبانی می‌شوند باید یک diskspec ارائه شود، زیرا libvirt نام فایل‌ها را برای آن‌ها به طور خودکار تولید نمی‌کند. پارامتر اختیاری stype امکان کنترل نوع فایل منبع را فراهم می‌کند. مقادیر پشتیبانی‌شده عبارت‌اند از 'file' (پیش‌فرض) و 'block'. برای مستثنی کردن یک دیسک از اسنپ‌شات خارجی از --diskspec disk,snapshot=no استفاده کنید.

برای گنجاندن یک کامای صریح در disk یا file=name، آن را با یک کامای دوم گریز دهید. عبارت صریح --diskspec باید قبل از هر diskspec قرار گیرد، مگر اینکه هر سه مورد domain، name و description نیز حضور داشته باشند. برای نمونه، diskspec با مقدار "vda,snapshot=external,file=/path/to,,new" به XML زیر منجر می‌شود:

<disk name='vda' snapshot='external'>
  <source file='/path/to,new'/>
</disk>

اگر --reuse-external مشخص شده باشد و XML دامنه یا گزینهٔ diskspec درخواست یک اسنپ‌شات خارجی با مقصد یک فایل موجود را داشته باشند، آنگاه مقصد باید وجود داشته و از قبل با فرمت و فرادادهٔ صحیح ایجاد شده باشد. سپس از فایل دوباره استفاده می‌شود؛ در غیر این صورت، برای جلوگیری از دست رفتن محتوای فایل‌های موجود، از ایجاد اسنپ‌شات خودداری می‌شود.

اگر --quiesce مشخص شده باشد، libvirt تلاش خواهد کرد از guest agent برای منجمد کردن (freeze) و رفع انجماد (unfreeze) سیستم‌های فایل متصل‌شدهٔ دامنه استفاده کند. با این حال، اگر دامنه فاقد guest agent باشد، ایجاد اسنپ‌شات شکست خواهد خورد. در حال حاضر، این حالت نیازمند فرستادن --disk-only نیز می‌باشد.

اگر --no-metadata مشخص شده باشد، داده‌های اسنپ‌شات ایجاد می‌شوند اما هرگونه فراداده بی‌درنگ دور ریخته می‌شود (بدین معنا که libvirt اسنپ‌شات را به عنوان اسنپ‌شات فعلی در نظر نمی‌گیرد و نمی‌تواند به آن بازگردد، مگر اینکه بعداً از snapshot-create برای معرفی دوبارهٔ فراداده به libvirt استفاده شود).

اگر --atomic مشخص شده باشد، libvirt تضمین می‌کند که اسنپ‌شات یا با موفقیت انجام شود، یا بدون هیچ تغییری شکست بخورد؛ همهٔ هایپروایزرها از این قابلیت پشتیبانی نمی‌کنند. اگر این پرچم مشخص نشود، ممکن است برخی هایپروایزرها پس از انجام جزئی عملیات شکست بخورند، و باید از dumpxml برای بررسی رخ دادن هرگونه تغییرات جزئی استفاده شود.

اگر --live مشخص شده باشد، libvirt در حین اجرای مهمان اسنپ‌شات می‌گیرد. این امر اندازهٔ ایمیج حافظه در اسنپ‌شات خارجی را افزایش می‌دهد. این ویژگی در حال حاضر تنها برای اسنپ‌شات‌های خارجی کامل سیستم پشتیبانی می‌شود.

در حال حاضر، ایجاد اسنپ‌شات در دامنه‌ای که دارای checkpoint است ممکن نیست، هرچند این محدودیت در نسخه‌های آینده برداشته خواهد شد.

به صورت اختیاری، گزینهٔ --validate می‌تواند برای اعتبارسنجی سند XML که به طور داخلی توسط این دستور تولید شده است در برابر شِمای RNG داخلی ارسال شود..SS snapshot-current

سینتکس:

snapshot-current domain {[--name] | [--security-info] | [snapshotname]}

بدون snapshotname، این دستور خروجی XML اسنپ‌شات را برای اسنپ‌شات فعلی دامنه (در صورت وجود) نمایش می‌دهد. اگر --name مشخص شده باشد، به جای کل XML، فقط نام اسنپ‌شات فعلی نمایش داده می‌شود. در غیر این صورت، استفاده از --security-info اطلاعات حساس امنیتی را نیز در XML شامل خواهد کرد.

همراه با snapshotname، این درخواستی است برای تبدیل اسنپ‌شات نام‌برده موجود به اسنپ‌شات فعلی، بدون بازگردانی دامنه.

snapshot-edit

سینتکس:

snapshot-edit domain [snapshotname] [--current] {[--rename] | [--clone]}

ویرایش فایل پیکربندی XML برای snapshotname یک دامنه. اگر هر دو snapshotname و --current مشخص شده باشند، اسنپ‌شات ویرایش‌شده را نیز وادار می‌کند تا به اسنپ‌شات فعلی تبدیل شود. اگر snapshotname حذف شود، برای ویرایش اسنپ‌شات فعلی باید --current ارائه گردد.

این دستور معادل است با:

virsh snapshot-dumpxml dom name > snapshot.xml
vi snapshot.xml (or make changes with your other text editor)
virsh snapshot-create dom snapshot.xml --redefine [--current]

با این تفاوت که برخی بررسی‌های خطا را نیز انجام می‌دهد.

ویرایشگر مورد استفاده می‌تواند توسط متغیرهای محیطی $VISUAL یا $EDITOR تعیین شود، و پیش‌فرض آن vi است.

اگر --rename مشخص شود، ویرایش‌ها می‌توانند نام اسنپ‌شات را تغییر دهند. اگر --clone مشخص شود، تغییر نام اسنپ‌شات یک کلون از فراداده اسنپ‌شات ایجاد خواهد کرد. اگر هیچ‌کدام مشخص نشوند، ویرایش‌ها نباید نام اسنپ‌شات را تغییر دهند. توجه داشته باشید که تغییر نام اسنپ‌شات باید با احتیاط انجام شود، زیرا محتوای برخی از اسنپ‌شات‌ها، مانند اسنپ‌شات‌های داخلی درون یک فایل qcow2 منفرد، فقط از طریق همان نام اولیه قابل دسترسی هستند.

snapshot-info

سینتکس:

snapshot-info domain {snapshot | --current}

نمایش اطلاعات پایه‌ای درباره یک <snapshot> نام‌برده، یا اسنپ‌شات فعلی با --current.

snapshot-list

سینتکس:

snapshot-list domain [--metadata] [--no-metadata]
   [{--parent | --roots | [{--tree | --name}]}] [--topological]
   [{[--from] snapshot | --current} [--descendants]]
   [--leaves] [--no-leaves] [--inactive] [--active]
   [--disk-only] [--internal] [--external]

فهرست کردن تمام اسنپ‌شات‌های موجود برای دامنه داده‌شده؛ به طور پیش‌فرض ستون‌هایی برای نام اسنپ‌شات، زمان ایجاد، و وضعیت دامنه نمایش داده می‌شود.

در حالت عادی، خروجی قالبی جدول بر اساس نام اسنپ‌شات مرتب می‌شود؛ استفاده از --topological به جای آن خروجی را طوری مرتب می‌کند که هیچ فرزندی پیش از اجداد خود فهرست نشود (اگرچه ممکن است بیش از یک ترتیب ممکن با این ویژگی وجود داشته باشد).

اگر --parent مشخص شده باشد، ستونی به جدول خروجی اضافه می‌کند که نام والد هر اسنپ‌شات را ارائه می‌دهد. اگر --roots مشخص شده باشد، فهرست فقط به اسنپ‌شات‌هایی که هیچ والدی ندارند فیلتر می‌شود. اگر --tree مشخص شده باشد، خروجی در قالب درختی خواهد بود و فقط نام اسنپ‌شات‌ها را فهرست می‌کند. این سه گزینه مانعة‌الجمع هستند.

اگر --name مشخص شده باشد فقط نام اسنپ‌شات چاپ می‌شود که در صورت استفاده از --parent نیز، به صورت اختیاری نام اسنپ‌شات والد جدا شده با نویسه tab به دنبال آن می‌آید. این گزینه با --tree مانعة‌الجمع است.

اگر --from ارائه شود، فهرست به اسنپ‌شات‌هایی که فرزندان snapshot داده‌شده هستند فیلتر می‌شود؛ یا اگر --current ارائه شود، از اسنپ‌شات فعلی شروع می‌کند. هنگامی که به تنهایی یا همراه با --parent استفاده شود، فهرست محدود به فرزندان مستقیم است مگر اینکه --descendants نیز وجود داشته باشد. هنگام استفاده با --tree، استفاده از --descendants به صورت ضمنی در نظر گرفته می‌شود. این گزینه با --roots سازگار نیست. توجه داشته باشید که نقطه شروع --from یا --current در فهرست گنجانده نمی‌شود مگر اینکه گزینه --tree نیز وجود داشته باشد.

اگر --leaves مشخص شده باشد، فهرست فقط به اسنپ‌شات‌هایی فیلتر می‌شود که هیچ فرزندی ندارند. به همین ترتیب، اگر --no-leaves مشخص شده باشد، فهرست فقط به اسنپ‌شات‌های دارای فرزند فیلتر خواهد شد. (توجه داشته باشید که حذف هر دو گزینه هیچ فیلتری اعمال نمی‌کند، در حالی که ارائه هر دو گزینه بسته به اینکه سرور پرچم‌ها را تشخیص دهد یا خیر، یا همان فهرست را تولید می‌کند یا با خطا مواجه می‌شود). گزینه‌های فیلتر کردن با --tree سازگار نیستند.

اگر --metadata مشخص شده باشد، فهرست فقط به اسنپ‌شات‌هایی فیلتر می‌شود که با فراداده libvirt مرتبط هستند، و در نتیجه از undefine کردن یک ماشین مهمان دائمی جلوگیری می‌کنند، یا با destroy یک دامنه گذرا از بین می‌روند. به همین ترتیب، اگر --no-metadata مشخص شده باشد، فهرست فقط به اسنپ‌شات‌هایی فیلتر می‌شود که بدون نیاز به فراداده libvirt وجود دارند.

اگر --inactive مشخص شده باشد، فهرست به اسنپ‌شات‌هایی فیلتر می‌شود که هنگام خاموش بودن دامنه گرفته شده‌اند. اگر --active مشخص شده باشد، فهرست به اسنپ‌شات‌هایی فیلتر می‌شود که هنگام روشن و در حال اجرا بودن دامنه گرفته شده‌اند، و اسنپ‌شات شامل وضعیت حافظه برای بازگشت به آن حالت اجرا است. اگر --disk-only مشخص شده باشد، فهرست به اسنپ‌شات‌هایی فیلتر می‌شود که در زمان اجرای دامنه گرفته شده‌اند، اما اسنپ‌شات فقط شامل وضعیت دیسک است.

اگر --internal مشخص شده باشد، فهرست به اسنپ‌شات‌هایی فیلتر می‌شود که از فضای ذخیره‌سازی داخلی ایمیج‌های دیسک موجود استفاده می‌کنند. اگر --external مشخص شده باشد، فهرست به اسنپ‌شات‌هایی فیلتر می‌شود که از فایل‌های خارجی برای ایمیج‌های دیسک یا وضعیت حافظه استفاده می‌کنند..SS snapshot-dumpxml

نحو:

snapshot-dumpxml [--security-info] [--xpath EXPRESSION] [--wrap]
                 domain snapshot

خروجی XML اسنپ‌شات را برای اسنپ‌شاتی از دامنه با نام snapshot نمایش می‌دهد. استفاده از --security-info همچنین اطلاعات حساس امنیتی را نیز شامل خواهد کرد. از snapshot-current برای دسترسی آسان به XML اسنپ‌شات فعلی استفاده کنید.

اگر آرگومان --xpath یک عبارت XPath ارائه دهد، آن عبارت بر روی خروجی XML ارزیابی شده و تنها گره‌های منطبق چاپ خواهند شد. رفتار پیش‌فرض این است که هر گره منطبق به عنوان یک سند مستقل چاپ شود؛ با این حال، جهت سهولت در پردازش‌های بیشتر، آرگومان --wrap باعث می‌شود گره‌های منطبق درون یک گره ریشه (root) مشترک قرار گیرند.

snapshot-parent

نحو:

snapshot-parent domain {snapshot | --current}

نام اسنپ‌شات والد (در صورت وجود) را برای snapshot مشخص‌شده، یا با --current برای اسنپ‌شات فعلی خروجی می‌دهد.

snapshot-revert

نحو:

snapshot-revert domain {snapshot | --current} [{--running | --paused}]
   [--force] [--reset-nvram]

دامنه‌ی داده‌شده را به اسنپ‌شات مشخص‌شده با snapshot، یا با استفاده از --current به اسنپ‌شات فعلی بازگردانی می‌کند. توجه داشته باشید که این یک عمل مخرب است؛ هرگونه تغییر در دامنه از زمان ثبت آخرین اسنپ‌شات از دست خواهد رفت. همچنین در نظر داشته باشید که وضعیت دامنه پس از تکمیل snapshot-revert، همان وضعیت دامنه در زمان ثبت اسنپ‌شات اولیه خواهد بود.

به طور معمول، بازگردانی به یک اسنپ‌شات، دامنه را در همان وضعیتی که هنگام ایجاد اسنپ‌شات داشت رها می‌کند؛ به جز اسنپ‌شات دیسک بدون وضعیت ماشین مجازی (vm state) که دامنه را در وضعیت غیرفعال (inactive) قرار می‌دهد. ارسال هر یک از پرچم‌های --running یا --paused تغییرات وضعیت دیگری را اعمال خواهد کرد (مانند بوت کردن یک دامنه غیرفعال، یا متوقف کردن موقت یک دامنه در حال اجرا). از آنجا که دامنه‌های گذرا (transient) نمی‌توانند غیرفعال باشند، هنگام بازگردانی به یک اسنپ‌شات دیسک از یک دامنه‌ی گذرا، استفاده از یکی از این پرچم‌ها الزامی است.

از نسخه 7.10.0 نرم‌افزار libvirt، فرایند ماشین مجازی همواره مجدداً راه‌اندازی می‌شود، بنابراین بند بعدی دیگر معتبر نیست. اگر متاداده‌ی اسنپ‌شات فاقد XML کامل ماشین مجازی باشد، دیگر امکان بازگردانی به چنین اسنپ‌شاتی وجود ندارد.

مواردی وجود دارد که بازگردانی اسنپ‌شات با ریسک اضافی همراه است و برای ادامه‌ی عملیات نیاز به استفاده از --force دارد:

اگر --reset-nvram مشخص شود، هرگونه فایل NVRAM/varstore موجود حذف شده و از روی قالب دست‌نخورده‌ی اولیه دوباره مقداردهی خواهد شد..SS snapshot-delete

نحو:

snapshot-delete domain {snapshot | --current}
   [--metadata] [{--children | --children-only}]

اسنپ‌شات مربوط به دامنه با نام snapshot، یا با استفاده از --current اسنپ‌شات کنونی را حذف می‌کند. اگر این اسنپ‌شات دارای اسنپ‌شات‌های فرزند باشد، تغییرات این اسنپ‌شات در فرزندان ادغام خواهد شد. اگر --children داده شود، این اسنپ‌شات و تمامی فرزندان آن حذف می‌شوند. اگر --children-only داده شود، تمامی فرزندان این اسنپ‌شات حذف می‌شوند اما خود این اسنپ‌شات دست‌نخورده باقی می‌ماند. این دو پرچم مانعة‌الجمع هستند.

اگر --metadata مشخص شود، تنها فرادادهٔ اسنپ‌شات که توسط libvirt نگهداری می‌شود حذف می‌گردد، در حالی که محتوای اسنپ‌شات برای دسترسی توسط ابزارهای خارجی دست‌نخورده باقی می‌ماند؛ در غیر این صورت، حذف یک اسنپ‌شات محتوای داده‌ها را نیز از آن نقطهٔ زمانی حذف می‌کند.

checkpoint-create

نحو:

checkpoint-create domain [xmlfile] { --redefine [--redefine-validate] | [--quiesce]}

یک چک‌پوینت برای دامنهٔ domain با ویژگی‌های مشخص‌شده در xmlfile که عنصر سطح‌بالای <domaincheckpoint> را توصیف می‌کند، ایجاد می‌کند. قالب فایل XML ورودی در برابر یک طرحوارهٔ داخلی RNG اعتبارسنجی می‌شود (مشابه با استفاده از ابزار virt-xml-validate(1)). اگر xmlfile به‌طور کامل نادیده گرفته شود، libvirt یک چک‌پوینت با نامی بر اساس زمان فعلی ایجاد خواهد کرد.

اگر --redefine مشخص شود، تمام عناصر XML تولیدشده توسط checkpoint-dumpxml معتبر هستند؛ این گزینه می‌تواند برای مهاجرت دادن سلسله‌مراتب چک‌پوینت از یک ماشین به ماشین دیگر، بازسازی سلسله‌مراتب در موردی که یک دامنهٔ گذرا از بین رفته و بعداً با همان نام و UUID دوباره ایجاد می‌شود، یا ایجاد تغییرات جزئی در فرادادهٔ چک‌پوینت (مانند جنبه‌های وابسته به میزبان در XML دامنه که درون چک‌پوینت گنجانده شده‌اند) استفاده شود. هنگامی که این پرچم داده شود، آرگومان xmlfile اجباری است.

اگر --redefine-validate به همراه --redefine مشخص شود، ناظر مجازی (hypervisor) اعتبارسنجی فراداده‌های مرتبط با چک‌پوینت ذخیره‌شده در مکان‌هایی غیر از XML چک‌پوینت را انجام می‌دهد. توجه داشته باشید که برخی از ناظرهای مجازی ممکن است برای انجام اعتبارسنجی نیاز داشته باشند که دامنه در حال اجرا باشد.

اگر --quiesce مشخص شود، libvirt سعی خواهد کرد از guest agent برای فریز کردن و از حالت فریز خارج کردن فایل‌سیستم‌های سوارشدهٔ دامنه استفاده کند. با این حال، اگر دامنه فاقد guest agent باشد، ایجاد چک‌پوینت با شکست مواجه خواهد شد.

وجود فرادادهٔ چک‌پوینت از تلاش‌ها برای undefine کردن یک مهمان مانا جلوگیری می‌کند. با این حال، برای دامنه‌های گذرا، زمانی که اجرای دامنه متوقف شود (چه با دستوری مانند destroy و چه بر اثر کنش داخلی مهمان)، فرادادهٔ چک‌پوینت بدون هیچ هشداری از دست می‌رود.

در حال حاضر، امکان ایجاد چک‌پوینت در دامنه‌ای که دارای اسنپ‌شات است وجود ندارد، اگرچه این محدودیت در انتشار‌های آینده برداشته خواهد شد.

checkpoint-create-as

نحو:

checkpoint-create-as domain [--print-xml] [name]
   [description] [--quiesce] [--diskspec] diskspec]...

یک چک‌پوینت برای دامنهٔ domain با <name> و <description> داده‌شده ایجاد می‌کند؛ اگر هر کدام از این مقادیر نادیده گرفته شوند، libvirt مقداری را انتخاب خواهد کرد. اگر --print-xml مشخص شود، به جای ایجاد واقعی چک‌پوینت، ساختار XML مناسب برای checkpoint-create در خروجی چاپ می‌شود.

گزینهٔ --diskspec می‌تواند برای کنترل این که کدام دیسک‌های مهمان در چک‌پوینت مشارکت داشته باشند استفاده شود. این گزینه می‌تواند با توجه به تعداد عناصر <disk> در XML دامنه، چندین بار تکرار شود. هر <diskspec> به فرمت disk[,checkpoint=type][,bitmap=name] است. عبارت تحت‌اللفظی --diskspec باید پیش از هر diskspec بیاید، مگر این‌که هر سه مقدار domain، name و description نیز وجود داشته باشند. به عنوان مثال، یک diskspec به صورت "vda,checkpoint=bitmap,bitmap=map1" به XML زیر منجر می‌شود:

<disk name='vda' checkpoint='bitmap' bitmap='map1'/>

اگر --quiesce مشخص شود، libvirt سعی خواهد کرد از guest agent برای فریز کردن و از حالت فریز خارج کردن فایل‌سیستم‌های سوارشدهٔ دامنه استفاده کند. با این حال، اگر دامنه فاقد guest agent باشد، ایجاد چک‌پوینت با شکست مواجه خواهد شد.

در حال حاضر، امکان ایجاد چک‌پوینت در دامنه‌ای که دارای اسنپ‌شات است وجود ندارد، اگرچه این محدودیت در انتشار‌های آینده برداشته خواهد شد..SS checkpoint-edit

نحو:

checkpoint-edit domain checkpointname

فایل پیکربندی XML مربوط به checkpointname یک domain را ویرایش می‌کند.

این معادل است با:

virsh checkpoint-dumpxml dom name > checkpoint.xml
vi checkpoint.xml (or make changes with your other text editor)
virsh checkpoint-create dom checkpoint.xml --redefine

با این تفاوت که برخی بررسی‌های خطا را انجام می‌دهد، از جمله اینکه ویرایش‌ها نباید تلاشی برای تغییر دادن نام checkpoint باشند.

ویرایشگر مورداستفاده می‌تواند توسط متغیرهای محیطی $VISUAL یا $EDITOR مشخص شود، و به‌طور پیش‌فرض vi است.

checkpoint-info

نحو:

checkpoint-info domain checkpoint

نمایش اطلاعات پایه‌ای درباره یک <checkpoint> مشخص‌شده.

checkpoint-list

نحو:

checkpoint-list domain [{--parent | --roots |
   [{--tree | --name}]}] [--topological]
   [[--from] checkpoint | [--descendants]]
   [--leaves] [--no-leaves]

تمام checkpointهای در دسترس برای domain داده‌شده را فهرست می‌کند، که به‌طور پیش‌فرض ستون‌هایی را برای نام checkpoint و زمان ایجاد آن نمایش می‌دهد.

به‌طور معمول، خروجی جدولی بر اساس نام checkpoint مرتب می‌شود؛ استفاده از --topological در عوض آن را به‌گونه‌ای مرتب می‌کند که هیچ فرزندی قبل از نیاکان خود فهرست نشود (اگرچه ممکن است بیش از یک ترتیب ممکن با این ویژگی وجود داشته باشد).

اگر --parent مشخص شود، ستونی به جدول خروجی اضافه می‌کند که نام والد هر checkpoint را نمایش می‌دهد. اگر --roots مشخص شود، فهرست تنها به checkpointهایی فیلتر می‌شود که هیچ والدی ندارند. اگر --tree مشخص شود، خروجی در قالب درختی خواهد بود و تنها نام checkpointها را فهرست می‌کند. این سه گزینه مانعة‌الجمع هستند.

اگر --name مشخص شود تنها نام checkpoint چاپ می‌شود و در صورتی که --parent نیز به کار رود، نام والد checkpoint که با tab جدا شده است نیز به دنبال آن می‌آید. این گزینه با --tree مانعة‌الجمع است.

اگر --from ارائه شود، فهرست را به checkpointهایی که فرزندان checkpoint داده‌شده هستند فیلتر می‌کند. هنگامی که به‌تنهایی یا همراه با --parent استفاده شود، فهرست به فرزندان مستقیم محدود می‌شود مگر اینکه --descendants نیز حضور داشته باشد. در صورت استفاده با --tree، استفاده از --descendants ضمنی خواهد بود. این گزینه با --roots سازگار نیست. توجه داشته باشید که نقطه شروع --from در فهرست گنجانده نمی‌شود مگر اینکه گزینه --tree نیز ارائه شده باشد.

اگر --leaves مشخص شود، فهرست تنها به checkpointهایی که فرزندی ندارند فیلتر می‌شود. به همین ترتیب، اگر --no-leaves مشخص شود، فهرست تنها به checkpointهایی دارای فرزند فیلتر خواهد شد. (توجه داشته باشید که نادیده گرفتن هر دو گزینه هیچ فیلتری اعمال نمی‌کند، در حالی که ارائه هر دو گزینه بسته به اینکه سرور پرچم‌ها را تشخیص می‌دهد یا خیر، منجر به همان فهرست یا خطا می‌شود). گزینه‌های فیلترسازی با --tree سازگار نیستند..SS checkpoint-dumpxml

نحو:

checkpoint-dumpxml [--security-info] [--no-domain] [--size]
                   [--xpath EXPRESSION] [--wrap] domain checkpoint

خروجی دادن XML نقطهٔ بازرسی برای نقطهٔ بازرسی دامنه به نام checkpoint. استفاده از --security-info اطلاعات حساس امنیتی را نیز شامل خواهد کرد.

استفاده از --size یک XML اضافه می‌کند که اندازهٔ فعلی داده‌های تغییریافتهٔ سیستم‌عامل میهمان از زمان ایجاد نقطهٔ بازرسی را بر حسب بایت نشان می‌دهد (اگرچه به یاد داشته باشید که فعالیت سیستم‌عامل میهمان میان بررسی اندازه و ایجاد واقعی نسخهٔ پشتیبان می‌تواند منجر به نیاز پشتیبان به فضای کمی بیشتر شود). توجه داشته باشید که برخی از هایپروایزرها ممکن است هنگام استفاده از --size نیازمند در حال اجرا بودن domain باشند.

استفاده از --no-domain عنصر <domain> را برای داشتن نمایی فشرده‌تر از خروجی حذف می‌کند.

اگر آرگومان --xpath یک عبارت XPath ارائه دهد، این عبارت روی خروجی XML ارزیابی شده و تنها گره‌های منطبق چاپ خواهند شد. رفتار پیش‌فرض چاپ هر گره منطبق به عنوان یک سند مستقل است، با این حال برای سهولت در پردازش‌های بیشتر، آرگومان --wrap باعث می‌شود که گره‌های منطبق درون یک گره ریشهٔ مشترک قرار گیرند.

checkpoint-parent

نحو:

checkpoint-parent domain checkpoint

خروجی دادن نام نقطهٔ بازرسی والد (در صورت وجود) برای checkpoint داده‌شده.

checkpoint-delete

نحو:

checkpoint-delete domain checkpoint
   [--metadata] [{--children | --children-only}]

حذف نقطهٔ بازرسی برای دامنه به نام checkpoint. سابقهٔ اینکه کدام بخش‌های دیسک از زمان این نقطهٔ بازرسی تغییر کرده‌اند در نقطهٔ بازرسی والد (در صورت وجود) ادغام می‌شوند. اگر --children داده شود، این نقطهٔ بازرسی و تمامی فرزندان آن حذف خواهند شد. اگر --children-only داده شود، تمامی فرزندان این نقطهٔ بازرسی حذف می‌شوند اما خود این نقطهٔ بازرسی دست‌نخورده باقی می‌ماند. این دو گزینه مانعة‌الجمع هستند.

اگر --metadata مشخص شود، تنها فرادادهٔ نقطهٔ بازرسی که توسط libvirt نگهداری می‌شود حذف خواهد شد، در حالی که محتوای نقطهٔ بازرسی برای دسترسی توسط ابزارهای خارجی دست‌نخورده باقی می‌ماند؛ در غیر این صورت حذف یک نقطهٔ بازرسی همچنین قابلیت انجام پشتیبان‌گیری افزایشی از آن نقطهٔ زمانی را از بین می‌برد.

nwfilter-undefine

نحو:

nwfilter-undefine nwfilter-name

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

nwfilter-list

نحو:

nwfilter-list

فهرست کردن تمام فیلترهای شبکهٔ موجود.

nwfilter-dumpxml

نحو:

nwfilter-dumpxml [--xpath EXPRESSION] [--wrap] nwfilter-name

نمایش خروجی XML فیلتر شبکه.

اگر آرگومان --xpath یک عبارت XPath را ارائه دهد، روی خروجی XML ارزیابی شده و تنها گره‌های منطبق چاپ خواهند شد. رفتار پیش‌فرض چاپ هر گرهٔ منطبق به عنوان یک سند مستقل است؛ با این حال، جهت سهولت در پردازش‌های بعدی، آرگومان --wrap باعث می‌شود که گره‌های منطبق درون یک گرهٔ ریشهٔ مشترک قرار گیرند.

nwfilter-edit

نحو:

nwfilter-edit nwfilter-name

ویرایش XML یک فیلتر شبکه.

این دستور معادل است با:

virsh nwfilter-dumpxml myfilter > myfilter.xml
vi myfilter.xml (or make changes with your other text editor)
virsh nwfilter-define myfilter.xml

با این تفاوت که بررسی‌هایی برای بروز خطا انجام می‌دهد. فیلتر شبکهٔ جدید ممکن است به دلایلی مشابه آنچه در nwfilter-define ذکر شد رد شود.

ویرایشگرِ مورد استفاده می‌تواند توسط متغیرهای محیطی $VISUAL یا $EDITOR تعیین شود، و پیش‌فرض آن vi است..SH "دستورهای اتصال فیلتر شبکه (NWFILTER BINDING COMMANDS)"

دستورهای زیر اتصالات فیلتر شبکه را مدیریت می‌کنند. اتصالات فیلتر شبکه، ارتباط میان یک پورت شبکه و یک فیلتر شبکه را دنبال می‌کنند. به‌طور کلی این اتصالات هنگام افزودن یا حذف کارت‌های شبکه (NIC) در یک ماشین مهمان، به‌صورت خودکار توسط درایورهای هایپروایزر مدیریت می‌شوند.

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

nwfilter-binding-create

نحو:

nwfilter-binding-create xmlfile [--validate]

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

به‌صورت اختیاری، می‌توان قالب فایل XML ورودی را با استفاده از --validate در برابر یک شِمای داخلی RNG اعتبارسنجی کرد.

nwfilter-binding-delete

نحو:

nwfilter-binding-delete port-name

ارتباط یک پورت شبکه را از یک فیلتر شبکه قطع می‌کند. پشتیبان فیلتر شبکه بلافاصله قوانین فیلتر موجود روی پورت را حذف می‌کند. از این دستور می‌توان برای حذف اتصال پورت شبکه برای فیلتری که در حال حاضر توسط ماشین مهمان استفاده می‌شود، در زمان روشن بودن مهمان و بدون نیاز به راه‌اندازی مجدد آن بهره برد. بازگرداندن فیلتر اتصال پورت شبکه برای مهمان در حال اجرا با استفاده از nwfilter-binding-create انجام خواهد شد.

nwfilter-binding-list

نحو:

nwfilter-binding-list

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

nwfilter-binding-dumpxml

نحو:

nwfilter-binding-dumpxml [--xpath EXPRESSION] [--wrap] port-name

نمایش خروجی XML مربوط به اتصال فیلتر شبکه برای دستگاه شبکه‌ای به نام port-name.

اگر آرگومان --xpath یک عبارت XPath را مشخص کند، این عبارت در برابر خروجی XML ارزیابی شده و فقط گره‌های منطبق چاپ خواهند شد. رفتار پیش‌فرض این است که هر گره منطبق به‌عنوان یک سند مستقل چاپ شود؛ با این حال، برای سهولت در پردازش‌های بعدی، آرگومان --wrap باعث می‌شود که گره‌های منطبق در یک گره ریشه مشترک قرار گیرند..SH "دستورهای ویژهٔ ناظر مجازی (HYPERVISOR-SPECIFIC COMMANDS)"

نکته: استفاده از دستورهای زیر اکیداً منع شده است. این دستورها می‌توانند باعث سردرگمی libvirt شده و در عملیات‌های بعدی به رفتارهای نادرست منجر گردند. چنانچه از این دستورها استفاده کردید، لطفاً مشکلات رخ‌داده را به توسعه‌دهندگان libvirt گزارش ندهید؛ به این گزارش‌ها ترتیب اثر داده نخواهد شد. اگر دریافتید که این دستورها تنها راه دستیابی به مقصود شما هستند، بهتر است درخواست کنید که این قابلیت به‌عنوان یک ویژگی رسمی و درجه‌یک به کتابخانهٔ استاندارد libvirt افزوده شود.

qemu-attach

ساختار:

qemu-attach pid

یک فرایند QEMU که به‌طور جداگانه اجرا شده است را به راه‌انداز QEMU در libvirt متصل می‌کند. فرایند QEMU باید با یک اتصال مانیتور از طریق راه‌انداز UNIX ایجاد شده باشد. در حالت ایدئال، این فرایند باید با آرگومان '-name' نیز اجرا شده باشد.

$ qemu-kvm -cdrom ~/demo.iso \
    -monitor unix:/tmp/demo,server,nowait \
    -name foo \
    -uuid cece4f9f-dff0-575d-0e8e-01fe380f12ea  &
$ QEMUPID=$!
$ virsh qemu-attach $QEMUPID

انتظار نمی‌رود پس از اتصال به یک فرایند QEMU که از خارج راه‌اندازی شده، همهٔ توابع libvirt به‌درستی و پایدار کار کنند. ممکن است در مهاجرت ماشین با تغییر ABI مهمان مشکلاتی ایجاد شود و اتصال یا انفصال گرم قطعات (hotplug یا hotunplug) کار نکند. محیط متصل‌شده باید در وهلهٔ نخست صرفاً خواندنی در نظر گرفته شود.

qemu-monitor-command

ساختار:

qemu-monitor-command domain { [--hmp] | [--pretty] [--return-value] }
    [--pass-fds N,M,...] command...

یک دستور مانیتور دلخواه command را از طریق مانیتور QEMU به دامنهٔ domain ارسال می‌کند. نتایج دستور در stdout چاپ خواهد شد.

اگر بیش از یک آرگومان برای command وارد شود، قبل از ارسال این دستورِ واحد به مانیتور، آرگومان‌ها با یک فاصله در میانشان به یکدیگر الحاق می‌شوند.

توجه داشته باشید که libvirt برای ارتباط با qemu از QMP استفاده می‌کند، بنابراین command برای عملکرد صحیح باید یک JSON معتبر در قالب QMP باشد. اگر command یک شیء JSON نباشد، libvirt تلاش می‌کند تا آن را درون یک شیء JSON بسته‌بندی کند تا رابط کاربری ساده‌تری فراهم شود؛ مانند این گروه‌های دستوری با رفتار یکسان:

# simple command
$ virsh qemu-monitor-command VM commandname
$ virsh qemu-monitor-command VM '{"execute":"commandname"}'
# with arguments
$ virsh qemu-monitor-command VM commandname '"arg1":123' '"arg2":"test"'
$ virsh qemu-monitor-command VM commandname '{"arg1":123,"arg2":"test"}'
$ virsh qemu-monitor-command VM '{"execute":"commandname", "arguments":{"arg1":123,"arg2":"test"}}'

اگر --pretty داده شود، پاسخ QMP به‌صورت خوانا و زیبا چاپ می‌شود (pretty-printed).

اگر --return-value داده شود، به جای نمایش پاسخ کاملِ ارسالی از QEMU، فقط کلید 'return' از شیء پاسخ QMP استخراج و نمایش داده می‌شود.

اگر --hmp ارسال شود، دستور به عنوان یک دستورِ Human Monitor در نظر گرفته می‌شود و libvirt به‌طور خودکار آن را به QMP تبدیل کرده و خروجی را نیز مجدداً بازمی‌گرداند.

اگر --pass-fds مشخص شده باشد، آرگومان آن فهرستی از توصیف‌کننده‌های فایل (file descriptors) باز است که با کاما از هم جدا شده‌اند و باید همراه با دستور به qemu فرستاده شوند..SS qemu-agent-command

نحو:

qemu-agent-command domain [--timeout seconds | --async | --block] command...

ارسال یک دستور دلخواه عامل مهمان command به دامنهٔ domain از طریق QEMU agent. گزینه‌های --timeout، --async و --block مانعة‌الجمع هستند. گزینهٔ --timeout نیازمند مقدار زمان بر حسب ثانیه در seconds است و مقدار آن باید مثبت باشد. هنگامی که --async داده شود، دستور چه در صورت موفقیت و چه شکست، تا پایان مهلت زمانی منتظر می‌ماند. و هنگامی که --block مشخص شود، دستور با مهلت زمانی مسدودکننده برای همیشه منتظر می‌ماند.

qemu-monitor-event

نحو:

qemu-monitor-event [domain] [--event event-name]
  [--loop] [--timeout seconds] [--pretty] [--regex] [--no-case]
  [--timestamp]

منتظر رخداد رویدادهای دلخواه پایشگر QEMU می‌ماند و جزئیات رویدادها را به محض وقوع چاپ می‌کند. رویدادها می‌توانند به طور اختیاری بر اساس domain یا event-name فیلتر شوند. از دستور QMP با نام 'query-events' می‌توان از طریق qemu-monitor-command استفاده کرد تا مشخص شود چه رویدادهایی پشتیبانی می‌شوند. اگر از --regex استفاده شود، event-name به جای یک رشتهٔ دقیق، یک عبارت منظم پایه خواهد بود. اگر از --no-case استفاده شود، event-name بدون حساسیت به بزرگی و کوچکی حروف تطبیق داده خواهد شد.

به طور پیش‌فرض، این دستور تک‌مرحله‌ای (one-shot) است و پس از وقوع یک رویداد با موفقیت خاتمه می‌یابد؛ می‌توانید SIGINT را (معمولاً از طریق Ctrl-C) ارسال کنید تا فوراً خارج شوید. اگر --timeout مشخص شده باشد، دستور پس از سپری شدن seconds از انتظار برای رویدادها دست می‌کشد. با --loop، دستور تا زمان پایان مهلت زمانی یا فشرده شدن کلید وقفه، تمام رویدادها را چاپ می‌کند. اگر --pretty مشخص شده باشد، هرگونه جزئیات رویداد JSON برای خوانایی بهتر با آرایش زیبا چاپ می‌شود.

هنگامی که از --timestamp استفاده شود، یک برچسب زمانی خوانا برای انسان پیش از رویداد چاپ خواهد شد و اطلاعات زمان‌بندی ارائه‌شده توسط QEMU حذف می‌شود.

lxc-enter-namespace

نحو:

lxc-enter-namespace domain [--noseclabel] --
   /path/to/binary [arg1, [arg2, ...]]

وارد فضای نام (namespace) دامنهٔ domain شده و دستور /path/to/binary را با ارسال آرگومان‌های درخواست‌شده اجرا می‌کند. مسیر باینری نسبت به سیستم‌فایل ریشهٔ کانتینر است، نه سیستم‌فایل ریشهٔ میزبان. باینری متغیرهای محیطی / کنسول قابل مشاهده برای virsh را به ارث می‌برد. دستور با همان بافتار sVirt و جایابی cgroups مربوط به فرآیندهای درون کانتینر اجرا خواهد شد. این دستور فقط زمانی کار می‌کند که به راه‌انداز ناظر مجازی LXC متصل باشد. این دستور تنها در صورتی با موفقیت پایان می‌یابد که /path/to/binary وضعیت خروج 0 داشته باشد.

به طور پیش‌فرض، فرآیند جدید با برچسب امنیتی کانتینر والد جدید اجرا خواهد شد. از گزینهٔ --noseclabel استفاده کنید تا در عوض، فرآیند همان برچسب امنیتی virsh را حفظ کند.