virt-admin(1) Virtualization Support virt-admin(1)

virt-admin - رابط مدیریت دیمن

virt-admin [OPTION]... [COMMAND_STRING]

virt-admin [OPTION]... COMMAND [ARG]...

برنامه virt-admin رابط مدیریتی اصلی برای تغییر پیکربندی دیمن libvirt در زمان اجرا، تغییر رفتار دیمن، و همچنین نظارت و مدیریت کلیه کلاینت‌های متصل به دیمن است.

ساختار پایه بیشتر کاربردهای virt-admin به شرح زیر است:

virt-admin [OPTION]... <command> [ARG]...

که در آن command یکی از دستورات فهرست‌شده در ادامه است. هر دستوری که با # شروع شود، به عنوان کامنت در نظر گرفته شده و بی‌صدا نادیده گرفته می‌شود؛ سایر دستورات ناشناخته خطایابی و گزارش می‌شوند.

برنامه virt-admin می‌تواند هم برای اجرای یک COMMAND منفرد با وارد کردن دستور و آرگومان‌های آن در خط فرمان شل استفاده شود، و هم با یک COMMAND_STRING که یک تک‌آرگومان شل متشکل از چندین عملیات COMMAND و آرگومان‌های آن‌ها است که با فاصله ترکیب شده و با نقطه-ویرگول (;) یا خطوط جدید از یکدیگر جدا شده‌اند (جفت‌های بک‌اسلش-خط‌جدید خارج از نقل‌قول حذف می‌شوند). در داخل COMMAND_STRING، برنامه virt-admin همان کاراکترهای اسکیپ نقل‌قول تکی، دوتایی و بک‌اسلش را مانند شل تفسیر می‌کند؛ اگرچه هنگام ساختن تک‌آرگومان شل باید یک لایه اسکیپ شل اضافی اعمال کنید، و هر کلمه‌ای که با کاراکتر # بدون نقل‌قول شروع شود یک کامنت تلقی شده و تا پایان خط ادامه می‌یابد. اگر هیچ دستوری در خط فرمان داده نشود، virt-admin یک مفسر تعاملی کمینه را راه‌اندازی کرده و منتظر دستورات شما می‌ماند؛ در این حالت، دستور quit از برنامه خارج می‌شود.

برنامه virt-admin گزینه‌های (OPTIONS) زیر را درک می‌کند:

-c, --connect URI

اتصال به URI مشخص‌شده، همانند دستور connect، به جای اتصال پیش‌فرض. به بخش «نکات (NOTES)» مراجعه کنید.

-d, --debug LEVEL

فعال‌سازی پیام‌های اشکال‌زدایی در سطح عدد صحیح LEVEL و بالاتر. مقدار LEVEL می‌تواند بین 0 تا 4 باشد (پیش‌فرض). برای شرح هر یک از سطوح LEVEL، مستندات متغیر محیطی VIRT_ADMIN_DEBUG در ادامه را ببینید.

-h, --help

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

-l, --log FILE

ارسال جزئیات گزارش‌گیری به فایل FILE.

-q, --quiet

جلوگیری از نمایش پیام‌های اطلاعاتی اضافی.

-v, --version[=short]

نادیده گرفتن تمام آرگومان‌های دیگر و چاپ نگارش کتابخانه libvirt که virt-admin از آن ساخته شده است.

-V, --version=long

نادیده گرفتن تمام آرگومان‌های دیگر و چاپ نگارش کامل کتابخانه libvirt که virt-admin از آن ساخته شده است.

برنامه virt-admin بسته به اینکه سیستم شما از کدام مورد استفاده می‌کند، هم از دیمن یکپارچه libvirtd و هم از دیمن‌های ماژولار https://libvirt.org/daemons.html#modular-driver-daemons پشتیبانی می‌کند. نشانی URI اتصال مورد استفاده با -c/--connect یا دستور connect بر اساس نام دیمن تحت کنترل تعیین می‌شود؛ برای مثال: virtqemud:///system، libvirtd:///system.

اجرای virt-admin در هنگام برقراری ارتباط با نمونه سیستمی یک دیمن (URI منتهی به /system)، به دلیل کانال‌های ارتباطی به کار رفته برای گفتگو با دیمن، نیازمند امتیازات ریشه (root) است.

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

Syntax:

help [command-or-group]

این دستور تمام دستورات virt-admin را فهرست می‌کند. در صورت استفاده بدون گزینه، تمام دستورات در یک خط به ازای هر دستور، گروه‌بندی‌شده در دسته‌بندی‌های مرتبط و با نمایش کلیدواژه هر گروه فهرست می‌شوند.

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

Syntax:

quit
exit

خروج از این ترمینال تعاملی

Syntax:

version

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

مثال (Example):

$ virt-admin version
Compiled against library: libvirt 1.2.21
Using library: libvirt 1.2.21
Running against daemon: 1.2.20

Syntax:

cd [directory]

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

این دستور تنها در حالت تعاملی در دسترس است.

Syntax:

pwd

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

Syntax:

connect [URI]

اتصال (یا اتصال مجدد) به سرور مدیریتی یک دیمن. پارامتر URI نحوه اتصال به سرور مدیریتی را مشخص می‌کند. اگر متغیر محیطی LIBVIRT_ADMIN_DEFAULT_URI یا گزینه uri_default (به ادامه مراجعه کنید) تنظیم شده باشد، با هر بار اجرای دستوری که نیازمند یک اتصال فعال است، connect به صورت خودکار فراخوانی می‌شود. توجه داشته باشید که این موضوع تنها در صورتی صدق می‌کند که اصلاً اتصالی وجود نداشته باشد یا اتصال غیرفعال باشد.

برای انتخاب URI صحیح مربوط به دیمن libvirt، به بخش «نکات (NOTES)» مراجعه کنید.

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

Syntax:

uri

نشانی URI متعارف سرور مدیریتی را چاپ می‌کند که می‌تواند در حالت شل مفید باشد. اگر هیچ uri مشخص نشده باشد و نه متغیر محیطی LIBVIRT_ADMIN_DEFAULT_URI و نه گزینه uri_default (در libvirt-admin.conf) تنظیم نشده باشند، از libvirtd:///system استفاده می‌شود.

دستورات زیر امکان نظارت بر وضعیت دیمن و همچنین تغییر مستقیم پیکربندی داخلی آن را فراهم می‌کنند.

Syntax:

server-list

تمام سرورهای قابل مدیریتی را که در دیمنی که کلاینت در حال حاضر به آن متصل است قرار دارند، فهرست می‌کند.

Syntax:

daemon-log-filters [--filters string]

هنگام اجرا بدون آرگومان، مجموعه فیلترهای گزارش‌گیری تعریف‌شده در حال حاضر را بازمی‌گرداند. ارائه آرگومان باعث می‌شود این دستور مجموعه جدیدی از فیلترهای گزارش‌گیری را تعریف کند.

•
--filters

تعریف مجموعه جدیدی از فیلترهای گزارش‌گیری که در آن فیلترهای چندگانه با فاصله از هم جدا می‌شوند. هر فیلتر باید با قالبی که با جزئیات در /etc/libvirt/libvirtd.conf (بخش 'Logging filters') شرح داده شده است مطابقت داشته باشد.

مثال (Example):

برای تعریف فیلتری که تمام پیام‌های اشکال‌زدایی (DEBUG) مانند 'virObjectUnref' را سرکوب کند، از دستور زیر استفاده کنید:

$ virt-admin daemon-log-filters "4:util.object"

(به نماد '.' توجه داشته باشید که می‌تواند برای فیلترهای دقیق‌تر و متناسب با ماژول‌های خاص به کار رود؛ در مقابل، برای تاثیرگذاری بر کل دایرکتوری شامل چندین ماژول، این عبارت به "4:util" تبدیل می‌شود):

Syntax:

daemon-log-outputs [--outputs string]

هنگام اجرا بدون آرگومان، مجموعه خروجی‌های گزارش‌گیری تعریف‌شده در حال حاضر را بازمی‌گرداند. ارائه آرگومان باعث می‌شود این دستور مجموعه جدیدی از خروجی‌های گزارش‌گیری را تعریف کند.

•
--outputs

تعریف مجموعه جدیدی از خروجی‌های گزارش‌گیری که در آن خروجی‌های چندگانه با فاصله از هم جدا می‌شوند. هر خروجی باید با قالبی که با جزئیات در /etc/libvirt/libvirtd.conf (بخش 'Logging outputs') شرح داده شده است مطابقت داشته باشد.

مثال (Example):

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

$ virt-admin daemon-log-outputs "4:file:<absolute_path_to_the_file>"

برای تعریف چندین خروجی به صورت همزمان، آن‌ها باید با فاصله از هم جدا شوند:

$ virt-admin daemon-log-outputs "4:stderr 2:syslog:<msg_ident>"

Syntax:

daemon-timeout [--timeout] NUM

مدت‌زمان وقفه (timeout) دیمن را روی مقدار آرگومان '--timeout' تنظیم می‌کند. از --timeout 0 برای غیرفعال کردن خاموش شدن خودکار دیمن استفاده کنید.

Syntax:

daemon-shutdown [--preserve]

دستور به دیمن برای خروج برازنده (gracefully). اگر پرچم --preserve داده شود، وضعیت را به همان روشی ذخیره می‌کند که هنگام خاموش شدن سیستم‌عامل میزبان (دیمن‌های دارای امتیاز) یا خروج از نشست ورود کاربر (دیمن‌های بدون امتیاز) انجام می‌شود.

دستورات زیر پیکربندی داخلی سرور دیمن را دستکاری می‌کنند. سرور (server) با نام آن مشخص می‌شود.

Syntax:

server-threadpool-info server

بازیابی ویژگی‌های استخر نخ (threadpool) سرور. این ویژگی‌ها عبارتند از:

  • minWorkers به عنوان حد پایینی تعداد کارگران فعال،
  • maxWorkers به عنوان حد بالایی تعداد کارگران فعال،
  • nWorkers به عنوان تعداد فعلی کارگران در استخر نخ،
  • freeWorkers به عنوان تعداد فعلی کارگران در دسترس برای یک وظیفه،
  • prioWorkers به عنوان تعداد فعلی کارگران دارای اولویت در استخر نخ، و
  • jobQueueDepth به عنوان عمق فعلی صف کارهای استخر نخ.

پیش‌زمینه (Background)

هر سرور دیمن از یک استخر نخ برای انجام وظایف درخواست‌شده توسط کلاینت‌های متصل به آن استفاده می‌کند. هر بار که درخواست کلاینتی به سرور می‌رسد، بررسی می‌شود که آیا کارگری برای انجام وظیفه داده‌شده در دسترس است یا باید یک کارگر جدید برای این کار ایجاد شود (کارگر پس از پایان وظیفه، به جای نابود شدن، آزاد می‌شود). با این حال، ایجاد کارگران جدید تنها زمانی امکان‌پذیر است که تعداد فعلی کارگران هنوز زیر حد بالایی پیکربندی‌شده باشد. علاوه بر این کارگران «استاندارد»، یک استخر نخ شامل مجموعه ویژه‌ای از کارگران به نام کارگران اولویت‌دار نیز می‌باشد. هدف آن‌ها انجام وظایفی است که برخلاف وظایف انجام‌شده توسط کارگران عادی، کاملاً تحت کنترل libvirt هستند و libvirt تضمین می‌کند که چنین وظایفی نمی‌توانند معلق (hang) بمانند و بنابراین همیشه به پایان می‌رسند. نمونه‌ای از چنین وظیفه‌ای نابود کردن یک دامنه است:

$ virsh destroy <domain>.

Syntax:

server-threadpool-set server [--min-workers count] [--max-workers count] [--priority-workers count]

تغییر ویژگی‌های استخر نخ در یک سرور. تنها بخشی از کل ویژگی‌های شرح‌داده‌شده در server-threadpool-info برای تنظیم‌کننده پشتیبانی می‌شود.

  • --min-workers

    حد پایینی تعداد کارگران فعال در یک استخر نخ.

  • --max-workers

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

  • --priority-workers

    تعداد فعلی کارگران اولویت‌دار فعال در یک استخر نخ.

Syntax:

server-clients-info server

دریافت اطلاعات درباره تنظیمات فعلی محدودیت‌های مربوط به اتصال کلاینت‌های جدید. این اطلاعات شامل محدودیت‌های حداکثر تعداد کلاینت‌های متصل به server، حداکثر تعداد کلاینت‌های در انتظار احراز هویت جهت اتصال به سرور، و همچنین مقادیر زمان اجرای فعلی (به‌طور خاص تعداد فعلی کلاینت‌های متصل به server و تعداد فعلی کلاینت‌های در انتظار احراز هویت) می‌باشد.

مثال (Example):

# virt-admin server-clients-info libvirtd
nclients_max        : 120
nclients            : 3
nclients_unauth_max : 20
nclients_unauth     : 0

Syntax:

server-clients-set server [--max-clients count] [--max-unauth-clients count]

تنظیم محدودیت‌های جدید مربوط به کلاینت‌ها در server.

  • --max-clients

    تغییر حد بالایی حداکثر تعداد کلی کلاینت‌های متصل به server به مقدار count. مقدار این محدودیت همیشه باید بزرگ‌تر از مقدار --max-unauth-clients باشد.

  • --max-unauth-clients

    تغییر حد بالایی حداکثر تعداد کلاینت‌های در انتظار احراز هویت جهت اتصال به server به مقدار count. مقدار این محدودیت همیشه باید کمتر از مقدار --max-clients باشد.

Syntax:

server-update-tls server

به‌روزرسانی بافت TLS در server.

•
server

سرورهای موجود در یک دیمن. در حال حاضر تنها از 'libvirtd' یا 'virtproxyd' پشتیبانی می‌کند.

دستورات زیر امکان مدیریت و نظارت بر کلاینت‌های متصل به یکی از سرورهای موجود دیمن را فراهم می‌کنند. کلاینت‌ها با شناسه عددی (ID) خود مشخص می‌شوند که با فهرست کردن تمام کلاینت‌های متصل به یک سرور مشخص به دست می‌آید (به دستور client-list مراجعه کنید).

Syntax:

client-list server

چاپ جدولی شامل فهرست کلاینت‌های متصل به <server>، همچنین ارائه اطلاعات درباره نوع انتقال به کار رفته در اتصال کلاینت (انتقال‌های پشتیبانی‌شده شامل unix، tcp و tls هستند)، و همچنین ارائه اطلاعات درباره زمان اتصال کلاینت (از زمان محلی سیستم استفاده می‌شود).

Syntax:

client-info server client

بازیابی اطلاعات هویتی درباره client از server. ویژگی‌های بازگردانده‌شده ممکن است بسته به نوع انتقال اتصال به کار رفته متفاوت باشند. ویژگی‌های وابسته به نوع انتقال شامل شناسه فرآیند محلی کلاینت (pid)، شناسه کاربر (uid)، نام کاربری، و نام گروه، و همچنین نشانی سوکت مبدا راه دور است؛ به بخش مثال‌ها در ادامه مراجعه کنید.

از سوی دیگر، ویژگی‌های مستقل از نوع انتقال شامل بافت SELinux کلاینت (در صورت فعال بودن روی میزبان) و نام کاربری SASL (در صورت فعال بودن احراز هویت SASL در دیمن) هستند.

مثال‌ها (Examples):

# virt-admin client-info libvirtd 1
id             : 1
connection_time: 2016-05-03 13:27:04+0200
transport      : unix
readonly       : yes
unix_user_id   : 0
unix_user_name : root
unix_group_id  : 0
unix_group_name: root
unix_process_id: 10201
# virt-admin client-info libvirtd 2
id             : 2
connection_time: 2016-05-03 13:30:33+0200
transport      : tcp
readonly       : no
sock_addr      : 127.0.0.1:57060

Syntax:

client-disconnect server client

بستن یک اتصال برقرار شده از سوی client. آرگومان server نام سروری را که client در حال حاضر به آن متصل است مشخص می‌کند.

متغیرهای محیطی زیر می‌توانند برای تغییر رفتار virt-admin تنظیم شوند:

•
VIRT_ADMIN_DEBUG=<0 to 4>

فعال کردن اشکال‌زدایی پرحرف برای دستورات virt-admin. سطوح معتبر عبارتند از:

  • VIRT_ADMIN_DEBUG=0

    DEBUG - پیام‌ها در تمامی سطوح ثبت می‌شوند

  • VIRT_ADMIN_DEBUG=1

    INFO - پیام‌ها در سطوح INFO، NOTICE، WARNING و ERROR ثبت می‌شوند

  • VIRT_ADMIN_DEBUG=2

    NOTICE - پیام‌ها در سطوح NOTICE، WARNING و ERROR ثبت می‌شوند

  • VIRT_ADMIN_DEBUG=3

    WARNING - پیام‌ها در سطوح WARNING و ERROR ثبت می‌شوند

  • VIRT_ADMIN_DEBUG=4

    ERROR - پیام‌ها تنها در سطح ERROR ثبت می‌شوند.

  • VIRT_ADMIN_LOG_FILE=``LOGFILE``

    فایل ذخیره پیام‌های اشکال‌زدایی virt-admin.

  • LIBVIRT_ADMIN_DEFAULT_URI

    دیمنی که سرور مدیریت آن به عنوان پیش‌فرض متصل شود. این متغیر را روی یک URI با همان قالبی که در گزینه connect پذیرفته می‌شود تنظیم کنید. این متغیر بر URI پیش‌فرض تنظیم‌شده در هر فایل پیکربندی کلاینت ارجحیت دارد.

  • VIRT_ADMIN_HISTSIZE

    تعداد دستوراتی که باید در تاریخچه دستورات به خاطر سپرده شوند. مقدار پیش‌فرض 500 است.

  • LIBVIRT_DEBUG=LEVEL

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

  • LIBVIRT_DEBUG=1

    پیام‌ها در سطح DEBUG یا بالاتر

  • LIBVIRT_DEBUG=2

    پیام‌ها در سطح INFO یا بالاتر

  • LIBVIRT_DEBUG=3

    پیام‌ها در سطح WARNING یا بالاتر

  • LIBVIRT_DEBUG=4

    پیام‌ها در سطح ERROR یا بالاتر

برای اطلاعات بیشتر درباره گزینه‌های اشکال‌زدایی به پیوند زیر مراجعه کنید: https://libvirt.org/logging.html

لطفاً به فایل AUTHORS توزیع‌شده به همراه libvirt مراجعه کنید.

لطفاً هرگونه اشکال کشف‌شده را گزارش دهید. این کار می‌تواند از طریق یکی از راه‌های زیر انجام شود:

1.
فهرست پستی

https://libvirt.org/contact.html

2.
ردیاب اشکالات

https://libvirt.org/bugs.html

همچنین می‌توانید اشکالات را به توزیع‌کننده / ارائه‌دهنده نرم‌افزار خود گزارش دهید.

Copyright (C) 2015 Red Hat, Inc., and the authors listed in the libvirt AUTHORS file.

برنامه virt-admin تحت شرایط پروانه GNU LGPL v2+ توزیع می‌شود. این یک نرم‌افزار آزاد است؛ برای شرایط تکثیر به کد منبع مراجعه فرمایید. هیچ ضمانتی وجود ندارد؛ حتی برای قابل فروش بودن یا مناسب بودن برای یک هدف خاص.

virsh(1), virt-xml-validate(1), virt-host-validate(1), https://libvirt.org