virt-sparsify(1) Virtualization Support virt-sparsify(1)

virt-sparsify - تنک‌سازی دیسک ماشین مجازی و آزادسازی فضای خالی آن

virt-sparsify [--options] indisk outdisk
virt-sparsify [--options] --in-place disk

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

ابزار virt-sparsify ابزاری است که می‌تواند یک دیسک ماشین مجازی (یا هر ایمیج دیسک دیگری) را تنک (تخصیص‌یافته به صورت پویا یا thin-provisioned) کند. این بدان معناست که فضای خالی درون ایمیج دیسک می‌تواند مجدداً به فضای خالی در سیستم میزبان تبدیل شود.

ابزار virt-sparsify می‌تواند فضای خالی را در بیشتر سیستم‌های پرونده (مانند ext2/3/4، btrfs، NTFS و غیره) و همچنین در حجم‌های فیزیکی LVM مکان‌یابی کرده و تنک‌سازی کند.

همچنین virt-sparsify می‌تواند بین برخی از قالب‌های دیسک تبدیل انجام دهد؛ برای نمونه تبدیل یک ایمیج دیسک خام (raw) به یک ایمیج qcow2 با تخصیص پویا (thin-provisioned).

ابزار virt-sparsify می‌تواند روی هر ایمیج دیسکی کار کند، نه فقط ایمیج‌های مربوط به ماشین‌های مجازی. با این حال اگر یک ماشین مجازی دارای چند دیسک باشد و از مدیریت حجم (volume management) استفاده کند، virt-sparsify کار خواهد کرد اما چندان موثر نخواهد بود (http://bugzilla.redhat.com/887826).

اگر ورودی از نوع خام (raw) باشد، خروجی پیش‌فرض به صورت تنک خام (raw sparse) خواهد بود. باید اندازه خروجی را با استفاده از ابزاری بررسی کنید که مفهوم تنک بودن را درک می‌کند مانند "du -sh". این موضوع می‌تواند تفاوت چشمگیری ایجاد کند:

$ ls -lh test1.img
-rw-rw-r--. 1 rjones rjones 100M Aug  8 08:08 test1.img
$ du -sh test1.img
3.6M   test1.img

(اندازه ظاهری 100M را با اندازه واقعی 3.6M مقایسه کنید)

  • ماشین مجازی باید پیش از استفاده از این ابزار خاموش شود.
  • ابزار virt-sparsify ممکن است تا ۲ برابر اندازه مجازی ایمیج دیسک مبدا فضا نیاز داشته باشد (۱ رونوشت موقت + ۱ ایمیج مقصد). این حالت در بدترین شرایط رخ می‌دهد و معمولاً به فضای بسیار کمتری نیاز است.

    اگر از گزینه --in-place استفاده می‌کنید، به مقادیر زیادی از فضای موقت نیاز نخواهد بود.

  • ابزار virt-sparsify نمی‌تواند اندازه ایمیج‌های دیسک را تغییر دهد. برای این کار، از virt-resize(1) استفاده کنید.
  • ابزار virt-sparsify نمی‌تواند دیسک‌های رمزگذاری‌شده را پردازش کند. بسته Libguestfs از دیسک‌های رمزگذاری‌شده پشتیبانی می‌کند، اما خود دیسک‌های رمزگذاری‌شده نمی‌توانند تنک‌سازی شوند.
  • ابزار virt-sparsify هنوز نمی‌تواند فضای میان پارتیشن‌ها را تنک‌سازی کند. توجه داشته باشید که این فضا اغلب برای موارد حیاتی مانند بوت‌لودرها استفاده می‌شود، بنابراین در واقع بلااستفاده نیست.
  • در حالت رونوشت (copy mode)، اسنپ‌شات‌های داخلی qcow2 به ایمیج مقصد کپی نمی‌شوند.

همچنین ممکن است پیش از شروع، تمایل داشته باشید صفحات راهنمای ابزارهای مرتبط virt-filesystems(1) و virt-df(1) را مطالعه کنید.

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

virt-sparsify indisk outdisk

که دیسک "indisk" را در "outdisk" کپی کرده و خروجی را تنک می‌سازد. پرونده "outdisk" ایجاد می‌شود، یا اگر از قبل وجود داشته باشد رونویسی خواهد شد. قالب دیسک ورودی تشخیص داده می‌شود (برای نمونه qcow2) و همان قالب برای دیسک خروجی استفاده می‌شود.

برای تبدیل میان قالب‌ها، از گزینه --convert استفاده کنید:

virt-sparsify disk.raw --convert qcow2 disk.qcow2

ابزار virt-sparsify تلاش می‌کند فضای خالی را در تمام سیستم‌های پرونده‌ای که درون ایمیج دیسک مبدا می‌یابد صفر کرده و تنک‌سازی کند. شما می‌توانید با دستور زیر آن را وادارید تا برخی سیستم‌های پرونده را نادیده بگیرد (فضای خالی آن‌ها را صفر نکند):

virt-sparsify --ignore /dev/sda1 indisk outdisk

برای مشاهده فهرستی از سیستم‌های پرونده درون یک ایمیج دیسک، virt-filesystems(1) را ببینید.

از نسخه 1.26 به بعد virt-sparsify، می‌توانید با اجرای دستور زیر یک ایمیج دیسک را درجا تنک‌سازی کنید:

virt-sparsify --in-place disk.img

نمایش راهنما.
بررسی می‌کند که آیا متغیر محیطی "TMPDIR" یا دایرکتوری مشخص‌شده با --tmp فضای کافی برای تکمیل عملیات دارد یا خیر. این مقدار فقط یک تخمین است.

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

  • آن را نادیده بگیرید (ignore)،
  • یک هشدار چاپ کرده و ادامه دهید (continue)،
  • هشدار داده (warn) و منتظر بمانید تا کاربر کلید Return را فشار دهد (این حالت پیش‌فرض است)، یا:
  • با خطا متوقف شده و خارج شوید (fail).

نمی‌توانید از این گزینه و --in-place به طور همزمان استفاده کنید.

استفاده از توالی‌های رنگی ANSI برای رنگی کردن پیام‌ها. این حالت در زمانی که خروجی یک tty باشد پیش‌فرض است. اگر خروجی برنامه به یک پرونده هدایت شود، توالی‌های رنگی ANSI غیرفعال می‌شوند مگر اینکه از این گزینه استفاده کنید.
فشرده‌سازی پرونده خروجی. این گزینه تنها در صورتی کار می‌کند که قالب خروجی "qcow2" باشد.

نمی‌توانید از این گزینه و --in-place به طور همزمان استفاده کنید.

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

قالب‌های خروجی پشتیبانی‌شده و شناخته‌شده عبارتند از: "raw"، "qcow2"، "vdi".

همچنین می‌توانید از هر قالبی که توسط برنامه qemu-img(1) پشتیبانی می‌شود استفاده کنید، مانند "vmdk"، اما پشتیبانی از سایر قالب‌ها به qemu وابسته است.

مشخص کردن گزینه --convert معمولاً ایده خوبی است، زیرا در این صورت virt-sparsify نیازی به حدس زدن قالب ورودی نخواهد داشت.

برای تنظیم دقیق قالب خروجی، ببینید: --compress، -o.

نمی‌توانید از این گزینه و --in-place به طور همزمان استفاده کنید.

هنگام درخواست کلیدها و عبارت‌های عبور، virt-sparsify معمولاً انعکاس (echo) ورودی را خاموش می‌کند تا نتوانید آنچه تایپ می‌کنید را ببینید. اگر نگران حملات تمپست (Tempest) نیستید و شخص دیگری در اتاق حضور ندارد، می‌توانید این گزینه را برای مشاهده آنچه تایپ می‌کنید مشخص کنید.
قالب ایمیج دیسک ورودی را مشخص می‌کند. اگر این پرچم داده نشود، قالب به طور خودکار از خود ایمیج تشخیص داده می‌شود.

اگر با ایمیج‌های دیسک مهمانِ غیرقابل اعتماد با قالب خام (raw) کار می‌کنید، باید مطمئن شوید که قالب همیشه به صراحت مشخص شده باشد.

سیستم پرونده مشخص‌شده را نادیده می‌گیرد.

هنگامی که از --in-place استفاده نمی‌شود: فضای خالی روی سیستم پرونده صفر نخواهد شد، اما بلوک‌های موجودِ حاوی صفر همچنان تنک‌سازی می‌شوند.

هنگام استفاده از --in-place، سیستم پرونده به طور کامل نادیده گرفته می‌شود.

در شکل دوم، این گزینه گروه حجم (volume group) نام‌برده‌شده را نادیده می‌گیرد. از نام گروه حجم بدون پیشوند /dev/ استفاده کنید، مانند --ignore vg_foo

می‌توانید این گزینه را چندین بار مشخص کنید.

به جای تنک‌سازی از طریق کپی، تنک‌سازی را به صورت درجا (in-place) انجام می‌دهد. بخش "تنک‌سازی درجا (IN-PLACE SPARSIFICATION)" را در زیر ببینید.
یک کلید برای LUKS مشخص می‌کند تا هنگام استفاده از بازرسی (inspection)، دستگاه LUKS به طور خودکار باز شود.
مقدار "NAME" نام دستگاه در libguestfs است (مانند "/dev/sda1"). مقدار "UUID" شناسه یکتای (UUID) دستگاه است. مقدار "all" به معنای امتحان کردن کلید روی هر دستگاه رمزگذاری‌شده است.

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

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

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

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

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

این گزینه برای ماشین‌خوان‌تر کردن خروجی هنگام پردازش توسط سایر برنامه‌ها، رابط‌های کاربری گرافیکی (GUI) و غیره استفاده می‌شود. بخش "خروجی ماشین‌خوان (MACHINE READABLE OUTPUT)" را در زیر ببینید.
گزینه(های) -o را به دستور qemu-img(1) ارسال می‌کند تا قالب خروجی را به طور دقیق تنظیم نماید. گزینه‌های موجود به قالب خروجی (به --convert مراجعه کنید) و نسخه نصب‌شده برنامه qemu-img بستگی دارند.

شما باید از -o حداکثر یک بار استفاده کنید. برای ارسال چندین گزینه، آن‌ها را با کاما جدا کنید، مانند:

virt-sparsify --convert qcow2 \
  -o cluster_size=512,preallocation=metadata ...

نمی‌توانید از این گزینه و --in-place به طور همزمان استفاده کنید.

این گزینه نوارهای پیشرفت و سایر خروجی‌های غیرضروری را غیرفعال می‌کند.
فقط در حالت کپی، از دستگاه یا دایرکتوری نام‌برده‌شده به عنوان مکان لایه همپوشانی موقت (temporary overlay) استفاده می‌کند (همچنین متغیر محیطی "TMPDIR" را در زیر ببینید).

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

اگر پارامتر یک دایرکتوری باشد، این کار معادل تنظیم متغیر محیطی "TMPDIR" است.

نمی‌توانید از این گزینه و --in-place به طور همزمان استفاده کنید.

فقط در حالت کپی، گزینه اختصاصی --tmp prebuilt:file (که در آن "prebuilt:" یک رشته متنی ثابت است) باعث می‌شود که virt-sparsify از پرونده "file" با قالب qcow2 به عنوان فضای موقت استفاده کند.
  • پرونده باید به تازگی با قالب qcow2 قالب‌بندی شده باشد و indisk به عنوان پرونده پشتیبان (backing file) آن تعیین شده باشد.
  • اگر virt-sparsify را مجدداً اجرا می‌کنید، باید پرونده را قبل از هر بار اجرا دوباره بسازید.
  • ابزار virt-sparsify پرونده را حذف نمی‌کند.

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

فعال کردن پیام‌های پرجزئیات برای اشکال‌زدایی.
نمایش شماره نسخه و خروج.
شکستن خطوط طولانی در پیام‌های خطا، هشدار و اطلاعاتی. این حالت در زمانی که خروجی یک tty باشد پیش‌فرض است. اگر خروجی برنامه به یک پرونده هدایت شود، شکستن خطوط غیرفعال می‌شود مگر اینکه از این گزینه استفاده کنید.
فعال کردن ردیابی (tracing) فراخوانی‌های رابط برنامه‌نویسی (API) در libguestfs.
صفر کردن محتویات پارتیشن یا حجم منطقی (logical volume) نام‌برده‌شده در مهمان. تمام داده‌های روی دستگاه از بین می‌رود، اما تنک‌سازی فوق‌العاده خواهد بود! می‌توانید این گزینه را چندین بار مشخص کنید.

از نسخه 1.26 به بعد virt-sparsify، این ابزار قادر است تنک‌سازی را به صورت درجا (به جای کپی کردن از یک دیسک ورودی به یک دیسک خروجی) انجام دهد. این روش کارآمدتر است، اما نمی‌تواند به اندازه روش تنک‌سازی با کپی فضا آزاد کند.

برای استفاده از این حالت، یک ایمیج دیسک را مشخص کنید که در همان محل ویرایش شود:

virt-sparsify --in-place disk.img

برخی از گزینه‌ها با این حالت سازگار نیستند: --convert، --compress و -o زیرا به تغییرات اساسی در قالب دیسک نیاز دارند؛ و --check-tmpdir زیرا به مقادیر زیادی فضای موقت نیازی نیست.

تنک‌سازی درجا با استفاده از پشتیبانی از discard (معروف به trim یا unmap) عمل می‌کند.

گزینه --machine-readable می‌تواند برای ماشین‌خوان‌تر کردن خروجی استفاده شود، که هنگام فراخوانی virt-sparsify از سایر برنامه‌ها، رابط‌های کاربری گرافیکی (GUI) و غیره کاربرد دارد.

دو راه برای استفاده از این گزینه وجود دارد.

روش اول استفاده از این گزینه به تنهایی برای پرس‌وجوی قابلیت‌های باینری virt-sparsify است. خروجی معمول شبیه به این است:

$ virt-sparsify --machine-readable
virt-sparsify
ntfs
btrfs

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

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

در حال حاضر این به این معناست:

1.
پیام‌های نوار پیشرفت را می‌توان با جستجوی این عبارت منظم (regex) از طریق خروجی استاندارد (stdout) استخراج و تجزیه کرد: 
^[0-9]+/[0-9]+$
2.
برنامه فراخواننده باید پیام‌های ارسال‌شده به stdout (به جز پیام‌های نوار پیشرفت) را به عنوان پیام‌های وضعیت در نظر بگیرد. آن‌ها را می‌توان لاگ کرد و/یا به کاربر نمایش داد.
3.
برنامه فراخواننده باید پیام‌های ارسال‌شده به stderr را به عنوان پیام‌های خطا در نظر بگیرد. علاوه بر این، در صورت بروز یک خطای مهلک، virt-sparsify با یک کد وضعیت غیرصفر خارج می‌شود.

تمامی نسخه‌های virt-sparsify از گزینه --machine-readable پشتیبانی کرده‌اند.

امکان تعیین یک رشته قالب برای کنترل خروجی وجود دارد؛ به "ADVANCED MACHINE READABLE OUTPUT" در guestfs(3) مراجعه کنید.

قابلیت «راه‌اندازی سریع» (fast startup) در ویندوز ۸ می‌تواند مانع از کارکرد درست virt-sparsify شود. به "WINDOWS HIBERNATION AND WINDOWS 8 FAST STARTUP" در guestfs(3) مراجعه کنید.

مکان دایرکتوری موقت مورد استفاده برای پرونده همپوشانی موقت (temporary overlay) که می‌تواند بسیار بزرگ باشد.

در نسخه 1.28 به بعد virt-sparsify، می‌توانید این متغیر محیطی را با استفاده از گزینه --tmp بازنویسی کنید.

شما باید اطمینان حاصل کنید که در بدترین حالت، فضای آزاد کافی برای یک نسخه کامل از دیسک مبدا (اندازه مجازی) وجود دارد، یا متغیر $TMPDIR را طوری تنظیم کنید که به دایرکتوری دیگری با فضای کافی اشاره کند.

مقدار پیش‌فرض این متغیر /tmp است.

توجه داشته باشید که اگر $TMPDIR یک tmpfs باشد (مثلاً اگر /tmp روی tmpfs قرار داشته باشد، یا اگر از "TMPDIR=/dev/shm" استفاده کنید)، اندازه tmpfs به طور پیش‌فرض حداکثر به نصف حافظه رم فیزیکی محدود می‌شود. اگر virt-sparsify از این مقدار فراتر رود، سیستم متوقف (hang) خواهد شد. راه حل این است که یا از یک دیسک واقعی استفاده کنید، یا حداکثر اندازه نقطه اتصال tmpfs را افزایش دهید، مانند:

mount -o remount,size=10G /tmp

اگر از گزینه --in-place استفاده می‌کنید، به مقادیر زیادی از فضای موقت نیاز نخواهد بود.

برای سایر متغیرهای محیطی، به بخش "ENVIRONMENT VARIABLES" در guestfs(3) مراجعه کنید.

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

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

اگر کد خروج برابر با 3 باشد و از گزینه --in-place استفاده شده باشد، نشان می‌دهد که پشتیبانی از discard در libguestfs در دسترس نیست، بنابراین باید از حالت کپی به جای آن استفاده شود.

virt-df(1), virt-filesystems(1), virt-resize(1), virt-rescue(1), guestfs(3), guestfish(1), truncate(1), fallocate(1), qemu-img(1), http://libguestfs.org

Richard W.M. Jones http://people.redhat.com/~rjones

Copyright (C) 2011-2025 Red Hat Inc.

این برنامه یک نرم‌افزار آزاد است؛ شما می‌توانید آن را تحت شرایط «مجوز عمومی همگانی گنو» (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