virt-sparsify(1) Virtualization Support virt-sparsify(1) نام (NAME) virt-sparsify - تنک‌سازی دیسک ماشین مجازی و آزادسازی فضای خالی آن خلاصه دستور (SYNOPSIS) virt-sparsify [--options] indisk outdisk virt-sparsify [--options] --in-place disk هشدار (WARNING) استفاده از "virt-sparsify" روی ماشین‌های مجازی روشن و فعال، یا به صورت همزمان با سایر ابزارهای ویرایش دیسک می‌تواند خطرناک باشد و به طور بالقوه منجر به آسیب‌دیدگی و خرابی دیسک شود. ماشین مجازی باید پیش از استفاده از این دستور خاموش شود، و ایمیج‌های دیسک نباید به صورت همزمان ویرایش شوند. توضیحات (DESCRIPTION) ابزار 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). نکته مهم درباره ایمیج‌های خروجی تنک (IMPORTANT NOTE ABOUT SPARSE OUTPUT IMAGES) اگر ورودی از نوع خام (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 مقایسه کنید) محدودیت‌های مهم (IMPORTANT LIMITATIONS) • ماشین مجازی باید پیش از استفاده از این ابزار خاموش شود. • ابزار virt-sparsify ممکن است تا ۲ برابر اندازه مجازی ایمیج دیسک مبدا فضا نیاز داشته باشد (۱ رونوشت موقت + ۱ ایمیج مقصد). این حالت در بدترین شرایط رخ می‌دهد و معمولاً به فضای بسیار کمتری نیاز است. اگر از گزینه --in-place استفاده می‌کنید، به مقادیر زیادی از فضای موقت نیاز نخواهد بود. • ابزار virt-sparsify نمی‌تواند اندازه ایمیج‌های دیسک را تغییر دهد. برای این کار، از virt-resize(1) استفاده کنید. • ابزار virt-sparsify نمی‌تواند دیسک‌های رمزگذاری‌شده را پردازش کند. بسته Libguestfs از دیسک‌های رمزگذاری‌شده پشتیبانی می‌کند، اما خود دیسک‌های رمزگذاری‌شده نمی‌توانند تنک‌سازی شوند. • ابزار virt-sparsify هنوز نمی‌تواند فضای میان پارتیشن‌ها را تنک‌سازی کند. توجه داشته باشید که این فضا اغلب برای موارد حیاتی مانند بوت‌لودرها استفاده می‌شود، بنابراین در واقع بلااستفاده نیست. • در حالت رونوشت (copy mode)، اسنپ‌شات‌های داخلی qcow2 به ایمیج مقصد کپی نمی‌شوند. همچنین ممکن است پیش از شروع، تمایل داشته باشید صفحات راهنمای ابزارهای مرتبط virt-filesystems(1) و virt-df(1) را مطالعه کنید. مثال‌ها (EXAMPLES) کاربرد معمول به این صورت است: 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 گزینه‌ها (OPTIONS) --help نمایش راهنما. --check-tmpdir ignore --check-tmpdir continue --check-tmpdir warn --check-tmpdir fail بررسی می‌کند که آیا متغیر محیطی "TMPDIR" یا دایرکتوری مشخص‌شده با --tmp فضای کافی برای تکمیل عملیات دارد یا خیر. این مقدار فقط یک تخمین است. اگر بررسی نشان‌دهنده یک مشکل باشد، می‌توانید یکی از این کارها را انجام دهید: • آن را نادیده بگیرید (ignore)، • یک هشدار چاپ کرده و ادامه دهید (continue)، • هشدار داده (warn) و منتظر بمانید تا کاربر کلید Return را فشار دهد (این حالت پیش‌فرض است)، یا: • با خطا متوقف شده و خارج شوید (fail). نمی‌توانید از این گزینه و --in-place به طور همزمان استفاده کنید. --colors --colours استفاده از توالی‌های رنگی ANSI برای رنگی کردن پیام‌ها. این حالت در زمانی که خروجی یک tty باشد پیش‌فرض است. اگر خروجی برنامه به یک پرونده هدایت شود، توالی‌های رنگی ANSI غیرفعال می‌شوند مگر اینکه از این گزینه استفاده کنید. --compress فشرده‌سازی پرونده خروجی. این گزینه تنها در صورتی کار می‌کند که قالب خروجی "qcow2" باشد. نمی‌توانید از این گزینه و --in-place به طور همزمان استفاده کنید. --convert raw --convert qcow2 --convert [other formats] استفاده از "output-format" به عنوان قالب ایمیج مقصد. اگر این گزینه مشخص نشود، از قالب ورودی استفاده می‌شود. قالب‌های خروجی پشتیبانی‌شده و شناخته‌شده عبارتند از: "raw"، "qcow2"، "vdi". همچنین می‌توانید از هر قالبی که توسط برنامه qemu-img(1) پشتیبانی می‌شود استفاده کنید، مانند "vmdk"، اما پشتیبانی از سایر قالب‌ها به qemu وابسته است. مشخص کردن گزینه --convert معمولاً ایده خوبی است، زیرا در این صورت virt-sparsify نیازی به حدس زدن قالب ورودی نخواهد داشت. برای تنظیم دقیق قالب خروجی، ببینید: --compress، -o. نمی‌توانید از این گزینه و --in-place به طور همزمان استفاده کنید. --echo-keys هنگام درخواست کلیدها و عبارت‌های عبور، virt-sparsify معمولاً انعکاس (echo) ورودی را خاموش می‌کند تا نتوانید آنچه تایپ می‌کنید را ببینید. اگر نگران حملات تمپست (Tempest) نیستید و شخص دیگری در اتاق حضور ندارد، می‌توانید این گزینه را برای مشاهده آنچه تایپ می‌کنید مشخص کنید. --format raw --format qcow2 قالب ایمیج دیسک ورودی را مشخص می‌کند. اگر این پرچم داده نشود، قالب به طور خودکار از خود ایمیج تشخیص داده می‌شود. اگر با ایمیج‌های دیسک مهمانِ غیرقابل اعتماد با قالب خام (raw) کار می‌کنید، باید مطمئن شوید که قالب همیشه به صراحت مشخص شده باشد. --ignore filesystem --ignore volgroup سیستم پرونده مشخص‌شده را نادیده می‌گیرد. هنگامی که از --in-place استفاده نمی‌شود: فضای خالی روی سیستم پرونده صفر نخواهد شد، اما بلوک‌های موجودِ حاوی صفر همچنان تنک‌سازی می‌شوند. هنگام استفاده از --in-place، سیستم پرونده به طور کامل نادیده گرفته می‌شود. در شکل دوم، این گزینه گروه حجم (volume group) نام‌برده‌شده را نادیده می‌گیرد. از نام گروه حجم بدون پیشوند /dev/ استفاده کنید، مانند --ignore vg_foo می‌توانید این گزینه را چندین بار مشخص کنید. --in-place به جای تنک‌سازی از طریق کپی، تنک‌سازی را به صورت درجا (in-place) انجام می‌دهد. بخش "تنک‌سازی درجا (IN-PLACE SPARSIFICATION)" را در زیر ببینید. --key SELECTOR یک کلید برای LUKS مشخص می‌کند تا هنگام استفاده از بازرسی (inspection)، دستگاه LUKS به طور خودکار باز شود. --key NAME:key:KEY_STRING --key UUID:key:KEY_STRING --key all:key:KEY_STRING مقدار "NAME" نام دستگاه در libguestfs است (مانند "/dev/sda1"). مقدار "UUID" شناسه یکتای (UUID) دستگاه است. مقدار "all" به معنای امتحان کردن کلید روی هر دستگاه رمزگذاری‌شده است. از "KEY_STRING" مشخص‌شده به عنوان عبارت عبور استفاده می‌کند. --key NAME:file:FILENAME --key UUID:file:FILENAME --key all:file:FILENAME عبارت عبور را از FILENAME می‌خواند. --key NAME:clevis --key UUID:clevis --key all:clevis تلاش برای بازگشایی قفل دستگاه بدون عبارت عبور با استفاده از Clevis و از طریق شبکه. لطفاً برای اطلاعات بیشتر درباره رمزگذاری دیسک متصل به شبکه (NBDE)، به بخش "ENCRYPTED DISKS" در guestfs(3) مراجعه کنید. توجه داشته باشید که اگر چنین گزینه‌ای در خط فرمان وجود داشته باشد، شبکه کاربری QEMU به طور خودکار برای اپلاینس libguestfs فعال خواهد شد. --keys-from-stdin پارامترهای کلید یا عبارت عبور را از ورودی استاندارد (stdin) می‌خواند. حالت پیش‌فرض این است که با باز کردن /dev/tty تلاش شود عبارت‌های عبور از کاربر خوانده شوند. اگر چند دستگاه رمزگذاری‌شده وجود داشته باشد، ممکن است لازم باشد چند کلید را در ورودی استاندارد، هر کدام در یک خط، وارد کنید. --machine-readable --machine-readable=format این گزینه برای ماشین‌خوان‌تر کردن خروجی هنگام پردازش توسط سایر برنامه‌ها، رابط‌های کاربری گرافیکی (GUI) و غیره استفاده می‌شود. بخش "خروجی ماشین‌خوان (MACHINE READABLE OUTPUT)" را در زیر ببینید. -o option[,option,...] گزینه(های) -o را به دستور qemu-img(1) ارسال می‌کند تا قالب خروجی را به طور دقیق تنظیم نماید. گزینه‌های موجود به قالب خروجی (به --convert مراجعه کنید) و نسخه نصب‌شده برنامه qemu-img بستگی دارند. شما باید از -o حداکثر یک بار استفاده کنید. برای ارسال چندین گزینه، آن‌ها را با کاما جدا کنید، مانند: virt-sparsify --convert qcow2 \ -o cluster_size=512,preallocation=metadata ... نمی‌توانید از این گزینه و --in-place به طور همزمان استفاده کنید. -q --quiet این گزینه نوارهای پیشرفت و سایر خروجی‌های غیرضروری را غیرفعال می‌کند. --tmp block_device --tmp dir فقط در حالت کپی، از دستگاه یا دایرکتوری نام‌برده‌شده به عنوان مکان لایه همپوشانی موقت (temporary overlay) استفاده می‌کند (همچنین متغیر محیطی "TMPDIR" را در زیر ببینید). اگر پارامتر داده‌شده یک دستگاه بلوکی (block device) باشد، عملیات نوشتن مستقیماً روی دستگاه بلوکی انجام می‌شود. توجه داشته باشید که این کار محتویات موجود در دستگاه بلوکی را پاک می‌کند. اگر پارامتر یک دایرکتوری باشد، این کار معادل تنظیم متغیر محیطی "TMPDIR" است. نمی‌توانید از این گزینه و --in-place به طور همزمان استفاده کنید. --tmp prebuilt:file فقط در حالت کپی، گزینه اختصاصی --tmp prebuilt:file (که در آن "prebuilt:" یک رشته متنی ثابت است) باعث می‌شود که virt-sparsify از پرونده "file" با قالب qcow2 به عنوان فضای موقت استفاده کند. • پرونده باید به تازگی با قالب qcow2 قالب‌بندی شده باشد و indisk به عنوان پرونده پشتیبان (backing file) آن تعیین شده باشد. • اگر virt-sparsify را مجدداً اجرا می‌کنید، باید پرونده را قبل از هر بار اجرا دوباره بسازید. • ابزار virt-sparsify پرونده را حذف نمی‌کند. این گزینه توسط oVirt استفاده می‌شود که به یک پرونده موقت با قالب‌بندی ویژه نیاز دارد. -v --verbose فعال کردن پیام‌های پرجزئیات برای اشکال‌زدایی. -V --version نمایش شماره نسخه و خروج. --wrap شکستن خطوط طولانی در پیام‌های خطا، هشدار و اطلاعاتی. این حالت در زمانی که خروجی یک tty باشد پیش‌فرض است. اگر خروجی برنامه به یک پرونده هدایت شود، شکستن خطوط غیرفعال می‌شود مگر اینکه از این گزینه استفاده کنید. -x فعال کردن ردیابی (tracing) فراخوانی‌های رابط برنامه‌نویسی (API) در libguestfs. --zero partition --zero logvol صفر کردن محتویات پارتیشن یا حجم منطقی (logical volume) نام‌برده‌شده در مهمان. تمام داده‌های روی دستگاه از بین می‌رود، اما تنک‌سازی فوق‌العاده خواهد بود! می‌توانید این گزینه را چندین بار مشخص کنید. تنک‌سازی درجا (IN-PLACE SPARSIFICATION) از نسخه 1.26 به بعد virt-sparsify، این ابزار قادر است تنک‌سازی را به صورت درجا (به جای کپی کردن از یک دیسک ورودی به یک دیسک خروجی) انجام دهد. این روش کارآمدتر است، اما نمی‌تواند به اندازه روش تنک‌سازی با کپی فضا آزاد کند. برای استفاده از این حالت، یک ایمیج دیسک را مشخص کنید که در همان محل ویرایش شود: virt-sparsify --in-place disk.img برخی از گزینه‌ها با این حالت سازگار نیستند: --convert، --compress و -o زیرا به تغییرات اساسی در قالب دیسک نیاز دارند؛ و --check-tmpdir زیرا به مقادیر زیادی فضای موقت نیازی نیست. تنک‌سازی درجا با استفاده از پشتیبانی از discard (معروف به trim یا unmap) عمل می‌کند. خروجی ماشین‌خوان (MACHINE READABLE OUTPUT) گزینه --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) مراجعه کنید. ویندوز ۸ (WINDOWS 8) قابلیت «راه‌اندازی سریع» (fast startup) در ویندوز ۸ می‌تواند مانع از کارکرد درست virt-sparsify شود. به "WINDOWS HIBERNATION AND WINDOWS 8 FAST STARTUP" در guestfs(3) مراجعه کنید. متغیرهای محیطی (ENVIRONMENT VARIABLES) TMPDIR مکان دایرکتوری موقت مورد استفاده برای پرونده همپوشانی موقت (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) مراجعه کنید. وضعیت خروج (EXIT STATUS) این برنامه در صورت تکمیل عملیات بدون خطا، مقدار 0 را برمی‌گرداند. (این لزوماً به این معنی نیست که فضایی آزاد شده است.) کد خروج غیرصفر نشان‌دهنده بروز خطا است. اگر کد خروج برابر با 3 باشد و از گزینه --in-place استفاده شده باشد، نشان می‌دهد که پشتیبانی از discard در libguestfs در دسترس نیست، بنابراین باید از حالت کپی به جای آن استفاده شود. همچنین ببینید (SEE ALSO) 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 نویسنده (AUTHOR) Richard W.M. Jones http://people.redhat.com/~rjones حق نشر (COPYRIGHT) Copyright (C) 2011-2025 Red Hat Inc. مجوز (LICENSE) این برنامه یک نرم‌افزار آزاد است؛ شما می‌توانید آن را تحت شرایط «مجوز عمومی همگانی گنو» (GNU General Public License) همان‌طور که توسط بنیاد نرم‌افزارهای آزاد منتشر شده است، بازتوزیع کرده و/یا تغییر دهید؛ چه نسخه ۲ مجوز، یا (به انتخاب خودتان) هر نسخه بعدی. این برنامه با این امید توزیع شده است که مفید واقع شود، اما بدون هیچ‌گونه ضمانتی؛ حتی بدون ضمانت ضمنی قابل فروش بودن یا مناسب بودن برای یک هدف خاص. برای جزئیات بیشتر به مجوز عمومی همگانی گنو مراجعه کنید. شما باید همراه با این برنامه یک نسخه از مجوز عمومی همگانی گنو را دریافت کرده باشید؛ در غیر این صورت، به بنیاد نرم‌افزارهای آزاد به نشانی زیر بنویسید: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. اشکالات (BUGS) برای مشاهده فهرست اشکالات مربوط به 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) را اجرا کرده و خروجی کامل و دست‌نخورده آن را در گزارش اشکال قرار دهید. guestfs-tools-1.56.0 2026-07-11 virt-sparsify(1)