virt-edit(1) Virtualization Support virt-edit(1)

virt-edit - ویرایش یک فایل در یک ماشین مجازی

virt-edit [--options] -d domname file [file ...]
virt-edit [--options] -a disk.img [-a disk.img ...] file [file ...]
virt-edit [-d domname|-a disk.img] file -e 'expr'

شیوه قدیمی:

 virt-edit domname file
 virt-edit disk.img [disk.img ...] file
استفاده از "virt-edit"
روی ماشین‌های مجازی روشن و در حال اجرا، یا هم‌زمان با سایر
ابزارهای ویرایش دیسک، می‌تواند خطرناک باشد و به طور بالقوه موجب خرابی
دیسک شود. ماشین مجازی باید پیش از استفاده از این دستور خاموش شود،
و ایمیج‌های دیسک نباید به صورت هم‌زمان ویرایش شوند.

دستور "virt-edit" یک ابزار خط فرمانی برای ویرایش "file" است، به‌طوری که هر "file" در ماشین مجازی مشخص‌شده (یا ایمیج دیسک) وجود دارد.

می‌توان چندین نام فایل را مشخص کرد که در این صورت هر یک به نوبت ویرایش می‌شوند. هر نام فایل باید یک مسیر کامل باشد که از دایرکتوری ریشه آغاز می‌شود (با '/' شروع می‌شود).

اگر تنها می‌خواهید فایلی را مشاهده کنید، از virt-cat(1) استفاده کنید.

برای موارد پیچیده‌تر باید ابزار guestfish(1) را بررسی کنید (بخش «USING GUESTFISH» را در ادامه ببینید).

ابزار "virt-edit" نمی‌تواند برای ایجاد یک فایل جدید استفاده شود. guestfish(1) می‌تواند این کار و بسیار بیشتر از آن را انجام دهد.

ویرایش تعاملی فایل‌های مشخص‌شده:

virt-edit -d mydomain /boot/grub/grub.conf
virt-edit -d mydomain /etc/passwd

برای ماشین‌های مهمان ویندوز، برخی از مسیرهای ویندوزی نیز قابل درک هستند:

virt-edit -d mywindomain 'c:\autoexec.bat'

در صورت نصب بودن Perl، می‌توانید فایل‌ها را به صورت غیرتعاملی نیز ویرایش کنید (بخش «NON-INTERACTIVE EDITING» را در ادامه ببینید). برای تغییر سطح پیش‌فرض init به ۵:

virt-edit -d mydomain /etc/inittab -e 's/^id:.*/id:5:initdefault:/'

نمایش راهنمای مختصر.
افزودن file که باید یک ایمیج دیسک از ماشین مجازی باشد. اگر ماشین مجازی دارای چندین دستگاه بلوکی است، باید همه آن‌ها را با گزینه‌های مجزا -a ارائه دهید.

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

افزودن یک دیسک دوردست (remote). بخش «ADDING REMOTE STORAGE» در guestfish(1) را ببینید.
ایجاد یک نسخه پشتیبان از فایل اصلی در ایمیج دیسک سیستم‌عامل مهمان. فایل پشتیبان همان نام فایل اصلی را به همراه پسوند افزودهٔ "extension" خواهد داشت.

معمولاً نخستین نویسه از "extension" یک نقطه "." است، بنابراین به این صورت می‌نویسید:

virt-edit -b .orig [etc]

به طور پیش‌فرض، هیچ فایل پشتیبانی ساخته نمی‌شود.

این پارامتر اندازهٔ سکتور ایمیج دیسک را تعیین می‌کند. این مقدار بر تمامی دیسک‌های بعدی که پس از این پارامتر صراحتاً افزوده شوند تأثیر می‌گذارد. استفاده از --blocksize بدون آرگومان، اندازه سکتور دیسک را به مقدار پیش‌فرض که معمولاً ۵۱۲ بایت است بازمی‌گرداند. همچنین مدخل "guestfs_add_drive_opts" در guestfs(3) را ببینید.
در صورت استفاده از libvirt، به URI مشخص‌شده متصل می‌شود. در صورت حذف، به هایپروایزر پیش‌فرض libvirt متصل خواهیم شد.

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

افزودن تمام دیسک‌ها از مهمان libvirt با نام مشخص‌شده. می‌توان از UUIDهای دامنه نیز به جای نام استفاده کرد.
هنگام درخواست کلیدها و گذرواژه‌ها، virt-edit معمولاً بازتاب نویسه‌ها (echoing) را غیرفعال می‌کند تا نتوانید آنچه را تایپ می‌کنید ببینید. اگر نگران حملات تمپست (Tempest) نیستید و فرد دیگری در اتاق حضور ندارد، می‌توانید این پرچم را مشخص کنید تا تایپ خود را ببینید.
به جای اجرای ویرایشگر بیرونی، عبارت پرل "EXPR" را به صورت غیرتعاملی بر روی تک‌تک خطوط فایل اعمال می‌کند. بخش «NON-INTERACTIVE EDITING» را در ادامه ببینید.

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

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

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

برای نمونه:

virt-edit --format=raw -a disk.img file

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

virt-edit --format=raw -a disk.img --format -a another.img file

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

اگر ایمیج‌های دیسک مهمان نامطمئن با قالب raw دارید، باید از این گزینه برای تعیین قالب دیسک استفاده کنید. این کار از یک آسیب‌پذیری امنیتی بالقوه با مهمان‌های مخرب جلوگیری می‌کند (CVE-2010-3851).

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

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

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

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

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

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

سوار کردن (mount) پارتیشن یا حجم منطقیِ (logical volume) نام‌برده بر روی نقطه اتصالِ داده‌شده.

اگر نقطه اتصال مشخص نشود، مقدار پیش‌فرض آن / خواهد بود.

مشخص کردن هر نقطه اتصالی، بازرسی مهمان (guest inspection) و سوار شدن ریشه و تمامی نقاط اتصال آن را غیرفعال می‌کند؛ بنابراین مطمئن شوید تمامی نقاط اتصالی را که برای کار با نام فایل‌های داده‌شده به عنوان آرگومان نیاز است، سوار کنید.

اگر نمی‌دانید یک تصویر دیسک شامل چه سیستم‌فایل‌هایی است، می‌توانید guestfish را بدون این گزینه اجرا کرده و سپس فهرست پارتیشن‌ها، سیستم‌فایل‌ها و LVهای موجود را بگیرید (دستورهای «list-partitions»، «list-filesystems» و «lvs» را ببینید)، یا می‌توانید از برنامه virt-filesystems(1) استفاده کنید.

بخش سوم (و به‌ندرت استفاده‌شده) از پارامتر mount، فهرستی از گزینه‌های سوار کردن است که برای سوار کردن سیستم‌فایل زیرین به کار می‌رود. اگر این مورد مشخص نشود، گزینه‌های سوار کردن یا یک رشته خالی خواهند بود یا "ro" (مورد دوم در حالتی است که پرچم --ro استفاده شده باشد). با تعیین گزینه‌های mount، این انتخاب پیش‌فرض را لغو می‌کنید. احتمالاً تنها زمانی از این مورد استفاده خواهید کرد که بخواهید در صورت پشتیبانی سیستم‌فایل، ACLها و/یا ویژگی‌های توسعه‌یافته (extended attributes) را فعال کنید:

-m /dev/sda1:/:acl,user_xattr

استفاده از این پرچم معادل استفاده از دستور "mount-options" است.

بخش چهارم پارامتر، گرداننده (driver) سیستم‌فایلی است که باید استفاده شود، مانند "ext3" یا "ntfs". به این بخش به‌ندرت نیاز می‌شود، اما در صورتی که چندین درایور برای یک سیستم‌فایل معتبر باشند (مانند: "ext2" و "ext3") یا اگر libguestfs یک سیستم‌فایل را به اشتباه شناسایی کند، می‌تواند سودمند باشد.

فعال کردن پیام‌های پرجزئیات برای اشکال‌زدایی.
نمایش شماره نسخه و خروج.
فعال کردن ردگیری فراخوانی‌های API در libguestfs..SH "آرگومان‌های خط فرمان سبک قدیم (OLD-STYLE COMMAND LINE ARGUMENTS)" نسخه‌های پیشین virt-edit به شما امکان می‌دادند یکی از این دو حالت را بنویسید:
virt-edit disk.img [disk.img ...] file

یا

virt-edit guestname file

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

به منظور سازگاری، سبک قدیمی همچنان پشتیبانی می‌شود.

دستور "virt-edit" به طور معمول $EDITOR (یا vi) را فراخوانی می‌کند تا مدیر سیستم بتواند فایل را به صورت تعاملی ویرایش کند.

همچنین دو روش برای استفاده از "virt-edit" درون اسکریپت‌ها جهت اعمال ویرایش‌های خودکار روی فایل‌ها وجود دارد. (توجه داشته باشید که اگرچه می‌توانید از "virt-edit" به این شکل استفاده کنید، اما نوشتن مستقیم اسکریپت‌ها با استفاده از API مربوط به libguestfs و ابزار Augeas برای ویرایش فایل‌های پیکربندی، کمتر مستعد خطا است.)

روش نخست این است که $EDITOR را موقتاً روی هر اسکریپت یا برنامه‌ای که می‌خواهید اجرا شود تنظیم کنید. اسکریپت به شکل "$EDITOR tmpfile" فراخوانی می‌شود و باید "tmpfile" را درجا به هر نحوی که می‌خواهد به‌روزرسانی کند.

روش دوم استفاده از پارامتر -e در "virt-edit" برای اجرای یک قطعه‌کد کوتاه Perl به سبک sed(1) است. برای نمونه، جهت جایگزینی تمام موارد "foo" با "bar" در یک فایل:

virt-edit -d domname filename -e 's/foo/bar/'

تمام توانایی عبارت‌های منظم Perl قابل استفاده است (به perlre(1) مراجعه کنید). برای نمونه، جهت حذف گذرواژه کاربر root می‌توانید بنویسید:

virt-edit -d domname /etc/passwd -e 's/^root:.*?:/root::/'

آنچه در واقع رخ می‌دهد این است که قطعه‌کد به عنوان یک عبارت Perl برای هر خط از فایل ارزیابی می‌شود. خط، شامل کاراکتر پایانی "\n"، در $_ ارسال می‌شود و عبارت باید $_ را به‌روزرسانی کند یا آن را بدون تغییر باقی بگذارد.

برای حذف یک خط، $_ را برابر با رشته خالی قرار دهید. برای نمونه، جهت حذف حساب کاربری "apache" از فایل گذرواژه می‌توانید دستور زیر را اجرا کنید:

virt-edit -d mydomain /etc/passwd -e '$_ = "" if /^apache:/'

برای درج یک خط، آن را به ابتدا یا انتهای $_ الحاق کنید. با این حال، افزودن خطوط به انتهای فایل از این طریق نسبتاً دشوار است، چرا که مفهومی تحت عنوان «آخرین خط فایل» وجود ندارد - عبارت شما صرفاً دوباره فراخوانی نمی‌شود. اگر می‌خواهید این کار را انجام دهید، ممکن است ترجیح دهید از روش اول (تنظیم $EDITOR) استفاده کنید.

متغیر $lineno حاوی شماره خط جاری است. طبق سنت همیشگی، اولین خط فایل شماره 1 است.

مقدار بازگشتی از عبارت نادیده گرفته می‌شود، اما عبارت می‌تواند تابع "die" را فراخوانی کند تا کل برنامه متوقف شود و فایل اصلی دست‌نخورده باقی بماند.

هنگام تطبیق انتهای خط به یاد داشته باشید که $_ ممکن است حاوی "\n" انتهایی، یا (برای فایل‌های DOS) حاوی "\r\n" باشد، یا اگر فایل به یک خط جدید ختم نشود، هیچ‌کدام از این‌ها را نداشته باشد. بنابراین برای تطبیق یا جایگزینی متنی در انتهای یک خط، از این عبارت منظم استفاده کنید:

/some text(\r?\n)?$/

یا به عنوان روش جایگزین، از تابع "chomp" در Perl استفاده کنید، با این احتیاط که خود $_ را chomp نکنید (زیرا این کار تمام خطوط جدید را از فایل حذف خواهد کرد):

 my $m = $_; chomp $m; $m =~ /some text$/
دستور "virt-edit" توانایی محدودی در درک حروف درایو و مسیرهای ویندوز (مانند E:\foo\bar.txt) دارد.
تنها و صرفاً اگر مهمان در حال اجرای ویندوز باشد، آن‌گاه:
  • پیشوندهای حرف درایو مانند "C:" با رجوع به رجیستری ویندوز (Windows Registry) به سیستم‌فایل صحیح تطبیق داده می‌شوند.
  • هر نویسهٔ بک‌اسلش ("\") در مسیر با یک اسلش رو به جلو جایگزین می‌شود تا libguestfs بتواند آن را پردازش کند.
  • مسیر بدون حساسیت به بزرگی و کوچکی حروف تطبیق داده می‌شود تا فایلی که باید ویرایش شود پیدا گردد.
برخی کاستی‌های شناخته‌شده وجود دارد:
  • ممکن است برخی از پیوندهای نمادین NTFS به درستی دنبال نشوند.
  • نقاط اتصال (junction points) در NTFS که در میان چند سیستم‌فایل قرار دارند دنبال نمی‌شوند.

ابزار guestfish(1) ابزاری قدرتمندتر و سطح‌پایین‌تر است که می‌توانید در صورت کار نکردن "virt-edit" از آن استفاده کنید.

استفاده از "virt-edit" تقریباً معادل اجرای دستور زیر است:

guestfish --rw -i -d domname edit /file

که در آن "domname" نام ماشین مهمان libvirt، و /file مسیر کامل فایل است.

دستور بالا از قابلیت بازرسی مهمان (guest inspection) در libguestfs استفاده می‌کند و بنابراین روی مهمان‌هایی که libguestfs نمی‌تواند آن‌ها را بازرسی کند، یا مواردی چون ایمیج‌های دیسک دلخواهی که حاوی مهمان نیستند، کار نمی‌کند. برای ویرایش مستقیم یک فایل روی یک ایمیج دیسک، استفاده کنید از:

guestfish --rw -a disk.img -m /dev/sda1 edit /file

که در آن disk.img ایمیج دیسک، /dev/sda1 سیستم‌فایل درون ایمیج دیسک برای ویرایش، و /file مسیر کامل فایل است.

دستور "virt-edit" قادر به ایجاد فایل‌های جدید نیست. در عوض از دستورهای guestfish نظیر "touch"، "write" یا "upload" استفاده کنید:

guestfish --rw -i -d domname touch /newfile
guestfish --rw -i -d domname write /newfile "new content"
guestfish --rw -i -d domname upload localfile /newfile

"EDITOR"
در صورت تعیین شدن، از این رشته به عنوان ویرایشگر استفاده می‌شود. ممکن است شامل آرگومان‌ها نیز باشد، مانند "emacs -nw"

اگر تعیین نشده باشد، از "vi" استفاده می‌شود.

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

guestfs(3), guestfish(1), virt-cat(1), virt-copy-in(1), virt-tar-in(1), http://libguestfs.org, perl(1), perlre(1)..SH "نویسندگان (AUTHORS)" Richard W.M. Jones http://people.redhat.com/~rjones

Copyright (C) 2009-2025 Red Hat Inc.

این برنامه یک نرم‌افزار آزاد است؛ شما می‌توانید آن را تحت شرایط «پروانه عمومی همگانی گنو» (GNU General Public License) همان‌طور که توسط «بنیاد نرم‌افزارهای آزاد» (Free Software Foundation) منتشر شده است؛ چه نسخهٔ ۲ پروانه و چه (به انتخاب خودتان) هر نسخهٔ متأخر دیگری، بازتوزیع کرده و/یا تغییر دهید.

این برنامه با این امید توزیع شده است که مفید باشد، اما بدون هرگونه ضمانت؛ حتی بدون ضمانت ضمنی «قابل فروش بودن» یا «مناسب بودن برای یک هدف خاص». برای جزئیات بیشتر «پروانه عمومی همگانی گنو» (GNU General Public License) را ببینید.

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

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

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

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

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