.\" Copyright 2007-2025 Tarsnap Backup Inc.
.\" All rights reserved.
.\"
.\" Portions of the file below are covered by the following license:
.\"
.\" Copyright (c) 2003-2007 Tim Kientzle
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: src/usr.bin/tar/bsdtar.1,v 1.46 2008/12/06 07:37:55 kientzle Exp $
.\"
.Dd March 20, 2025
.Dt TARSNAP 1
.Os
.Sh "نام (NAME)"
.Nm tarsnap
.Nd مدیریت نسخه‌های پشتیبان رمزشدهٔ راه دور
.Sh "خلاصه دستور (SYNOPSIS)"
.Nm
.Brq Fl c
.Fl -keyfile Ar key-file
.Fl -cachedir Ar cache-dir
.Fl f Ar archive-name
.Op Ar options
.Op Ar files | Ar directories
.Nm
.Brq Fl d
.Fl -keyfile Ar key-file
.Fl -cachedir Ar cache-dir
.Fl f Ar archive-name
.Op Ar options
.Nm
.Brq Fl t | Fl x
.Fl -keyfile Ar key-file
.Fl f Ar archive-name
.Op Ar options
.Op Ar patterns
.Nm
.Brq Fl r
.Fl -keyfile Ar key-file
.Fl f Ar archive-name
.Nm
.Brq Fl -list-archives
.Fl -keyfile Ar key-file
.Nm
.Brq Fl -print-stats
.Fl -keyfile Ar key-file
.Fl -cachedir Ar cache-dir
.Op Fl f Ar archive-name
.Nm
.Brq Fl -recover
.Fl -keyfile Ar key-file
.Fl -cachedir Ar cache-dir
.Nm
.Brq Fl -fsck
.Fl -keyfile Ar key-file
.Fl -cachedir Ar cache-dir
.Nm
.Brq Fl -fsck-prune
.Fl -keyfile Ar key-file
.Fl -cachedir Ar cache-dir
.Nm
.Brq Fl -initialize-cachedir
.Fl -keyfile Ar key-file
.Fl -cachedir Ar cache-dir
.Nm
.Brq Fl -nuke
.Fl -keyfile Ar key-file
.Nm
.Fl -verify-config
.Nm
.Fl -version
.Sh "توضیحات (DESCRIPTION)"
برنامهٔ
.Nm
نسخه‌های پشتیبان برخط را ایجاد، بازخوانی، حذف و مدیریت می‌کند.
.Pp
نخستین گزینه برای
.Nm
نشانگر حالت (mode) از فهرست زیر است:
.Bl -tag -compact -width indent
.It Fl c
ایجاد یک بایگانی شامل موارد و نام مشخص‌شده.
.It Fl d
حذف بایگانی مشخص‌شده.
.It Fl t
فهرست کردن محتویات بایگانی در stdout.
.It Fl x
استخراج از بایگانی بر روی دیسک.
.It Fl r
خواندن بایگانی مشخص‌شده، تبدیل آن به یک جریان tar، و نوشتن آن در stdout.
.It Fl -list-archives
چاپ نام بایگانی‌های ذخیره‌شده.
اگر پرچم
.Fl v
یک یا چند بار مشخص شود، زمان ایجاد هر بایگانی نیز چاپ می‌شود؛
اگر پرچم
.Fl v
دو یا چند بار مشخص شود، خط فرمانی که
.Nm
با آن برای ایجاد هر بایگانی فراخوانی شده بود نیز چاپ می‌شود.
.It Fl -print-stats
چاپ آمارهای سراسری دربارهٔ بایگانی‌های ذخیره‌شده، و در صورت تمایل اطلاعاتی دربارهٔ بایگانی(های) مشخص.
برای اطلاعات دربارهٔ قالب خروجی، بخش «چاپ آمار بایگانی (PRINTING ARCHIVE STATISTICS)» را در زیر ببینید.
.It Fl -recover
بازیابی یک بایگانی ناقص از یک نقطهٔ بازبینی (checkpoint) در صورتی که چنین بایگانی‌ای وجود داشته باشد.
این کار دفعهٔ بعدی که بایگانی‌ای ایجاد یا حذف شود نیز به‌طور خودکار انجام می‌پذیرد.
.It Fl -fsck
انجام برخی بررسی‌های یکپارچگی روی بایگانی‌های ذخیره‌شده، و بازسازی دایرکتوری حافظهٔ پنهان
.Ar cache-dir .
در صورت نامحتمل وجود بایگانی‌های خراب،
.Nm
خارج شده و درخواست می‌کند که با گزینهٔ
.Fl -fsck-prune
اجرا شود.
.It Fl -fsck-prune
اجرا مانند
.Fl -fsck ،
اما در صورت شناسایی بایگانی‌های خراب، داده‌های آسیب‌دیده هرس (prune) می‌شوند.
.It Fl -initialize-cachedir
ایجاد و مقداردهی اولیهٔ cachedir.
این گزینه برای رابط کاربری گرافیکی (GUI) در نظر گرفته شده و برای استفاده در خط فرمان نیازی به آن نیست.
.It Fl -nuke
حذف تمامی بایگانی‌های ذخیره‌شده.
برای محافظت در برابر از دست رفتن تصادفی داده‌ها، هنگام استفاده از دستور
.Fl -nuke ،
برنامهٔ
.Nm
از شما می‌خواهد عبارت "No Tomorrow" را تایپ کنید.
.It Fl -verify-config
بررسی خطاهای ساختاری در فایل(های) پیکربندی.
.It Fl -version
چاپ شماره نسخهٔ
.Nm
و خروج.
.El
.Pp
در حالت
.Fl c ،
هر فایل یا دایرکتوری مشخص‌شده، به ترتیبی که در خط فرمان تعیین شده است به بایگانی افزوده می‌شود.
به‌طور پیش‌فرض، محتویات هر دایرکتوری نیز بایگانی می‌شوند.
.Pp
در حالت
.Fl t
یا
.Fl x ،
کل خط فرمان پیش از باز شدن بایگانی خوانده و تجزیه می‌شود.
نام مسیرها یا الگوهای موجود در خط فرمان مشخص می‌کنند کدام موارد در بایگانی باید پردازش شوند.
الگوها همان الگوهای globbing به سبک شل هستند که در
.Xr tcsh 1
مستند شده‌اند.
توجه داشته باشید که این‌ها از قواعد POSIX برای تطبیق الگو پیروی می‌کنند؛ به عنوان مثال،
.Sq []
نویسه‌های خاصی هستند که می‌توان با یک بک‌اسلش از آن‌ها گریز (escape) کرد.
.Pp
دو عملیات ایجاد یا حذف هم‌روند را نمی‌توان با یک کلید یکسان انجام داد.
استخراج یا فهرست کردن بایگانی‌ها را می‌توان به‌صورت موازی با هر عملیات دیگری اجرا کرد.
.Sh "گزینه‌ها (OPTIONS)"
.Bl -tag -width indent
.It Cm @ Ns Pa archive-file
(تنها در حالت c)
فایل بایگانی مشخص‌شده خوانده می‌شود و مدخل‌های درون آن به بایگانی فعلی پیوست خواهند شد.
اگر
.Pa archive-file
برابر
.Dq -
باشد، بایگانی از ورودی استاندارد خوانده خواهد شد.
به عنوان مثال،
.Dl Nm Fl c Fl -keyfile Ar key-file Fl -cachedir Ar cache-dir Fl f Ar mybackup Cm @ Ns Pa backup.tar
فایل بایگانی
.Pa backup.tar
را از روی دیسک می‌خواند و آن را با استفاده از
.Nm
ذخیره می‌کند.
.It Cm @@ Ns Ar archive-name
(تنها در حالت c)
بایگانی مشخص‌شدهٔ
.Nm
خوانده می‌شود و مدخل‌های درون آن به بایگانی فعلی پیوست خواهند شد.
.It Fl -aggressive-networking
(تنها در حالت c)
استفاده از چندین اتصال TCP برای ارسال داده‌ها به کارساز
.Nm .
اگر نرخ بارگذاری به دلیل ازدحام شبکه محدود شده باشد تا اینکه توسط گلوگاه(های) منفرد محدود شود، این گزینه ممکن است به tarsnap امکان دهد بخش قابل توجهی بیشتری از پهنای باند موجود را مصرف کند، به قیمت کاهش سرعت سایر ترافیک‌های شبکه.
.It Fl -archive-names Ar filename
خواندن فهرستی از نام‌های بایگانی از
.Ar filename .
.It Fl C Ar directory
(تنها در حالت‌های c و x)
در حالت c، پیش از افزودن فایل‌های بعدی، دایرکتوری را تغییر می‌دهد.
در حالت x، پس از باز کردن بایگانی اما پیش از استخراج مدخل‌ها از بایگانی، دایرکتوری را تغییر می‌دهد.
.It Fl -cachedir Ar cache-dir
(تنها در حالت‌های c، d، print-stats و fsck)
اطلاعات مربوط به بایگانی‌های ذخیره‌شده توسط
.Nm
را در دایرکتوری
.Ar cache-dir
پنهان‌سازی (cache) می‌کند.
از محتویات این دایرکتوری توسط
.Nm
پشتیبان‌گیری نخواهد شد، بنابراین نباید برای هیچ هدف دیگری استفاده شود.
اگر دایرکتوری
.Ar cache-dir
از بین برود، می‌توان آن را با اجرای
.Nm Fl -fsck
بازسازی کرد.
.It Fl -check-links
(تنها در حالت c)
صدور پیام هشدار در صورتی که همهٔ پیوندهای مربوط به هر فایل بایگانی نشده باشند.
.It Fl -checkpoint-bytes Ar bytespercheckpoint
(تنها در حالت c)
ایجاد یک نقطهٔ بازبینی (checkpoint) پس از هر
.Ar bytespercheckpoint
بایت از داده‌های بارگذاری‌شده.
مقدار
.Ar bytespercheckpoint
باید حداقل ۱۰۰۰۰۰۰ باشد، و مقدار بالاتری پیشنهاد می‌شود زیرا ایجاد یک نقطهٔ بازبینی در یک بایگانی می‌تواند چند ثانیه طول کشیده و چند صد کیلوبایت پهنای باند مصرف کند.
.It Fl -chroot
(تنها در حالت x)
اجرای
.Fn chroot
به دایرکتوری جاری پس از پردازش هرگونه گزینهٔ
.Fl C
و پیش از استخراج هر فایلی.
.It Fl -configfile Ar filename
افزودن
.Ar filename
به فهرست فایل‌های پیکربندی که باید خوانده شوند؛ گزینه‌های تنظیم‌شده از این طریق بر فایل‌های پیکربندی پیش‌فرض اولویت دارند.
این گزینه می‌تواند چندین بار مشخص شود، که در این صورت تمامی فایل‌ها خوانده خواهند شد؛ در مواردی که تنظیمات با یکدیگر تداخل داشته باشند، فایل پیکربندیِ پیشین اولویت خواهد داشت.
.It Fl -creationtime Ar X
(تنها در حالت c)
مشخص کردن دستی زمان ایجاد (یک برچسب زمانی یونیکس یا unix timestamp) برای بایگانی.
بعید است این گزینه هنگام فراخوانی مستقیم tarsnap از خط فرمان کاربردی باشد.
.It Fl -csv-file Ar filename
(استفاده به همراه
.Fl -print-stats )
نوشتن آمارها در قالب CSV در یک فایل.
.It Fl -disk-pause Ar X
(تنها در حالت c)
مکث به مدت
.Ar X
میلی‌ثانیه بین ذخیره کردن مدخل‌های بایگانی و پس از هر ۶۴ کیلوبایت از داده‌های فایل.
این کار سرعت
.Nm
را کاهش داده و در نتیجه تأثیر آن بر سایر برنامه‌ها را کم می‌کند.
برای بایگانی کردن فایل‌هایی که روی دیسک ATA ذخیره شده‌اند و در حافظهٔ پنهان دیسک سیستم‌عامل قرار ندارند، مقدار
.Fl -disk-pause Ar 10
زمان صرف‌شده را تقریباً دو برابر خواهد کرد.
.It Fl -dry-run
(تنها در حالت c)
بایگانی را واقعاً ایجاد نمی‌کند؛ تنها انجام این کار را شبیه‌سازی می‌کند.
فهرست مسیرهای افزوده‌شده به یک بایگانی (در صورت استفاده از گزینهٔ
.Fl v ) ،
پیام‌های پیشرفت (در صورت استفاده از گزینهٔ
.Fl -progress-bytes )
و آمارهای نهایی چاپ‌شده (در صورت استفاده از گزینهٔ
.Fl -print-stats )
تقریباً با حالتی که
.Nm
بدون گزینهٔ
.Fl -dry-run
اجرا شود یکسان خواهند بود (معمولاً در حد چند کیلوبایت یا کسری از درصد تفاوت).
.Pp
توجه داشته باشید که گزینهٔ
.Fl -maxbw
در ترکیب با
.Fl -dry-run
کار نمی‌کند، زیرا در عمل هیچ پهنای باندی مصرف نمی‌شود، و از آنجا که
.Nm
هنگام اجرای آزمایشی (dry run) با کارساز
.Nm
تماس برقرار نمی‌کند، تلاشی را برای ایجاد بایگانی با نامی مشابه بایگانی موجود شناسایی نخواهد کرد.
اگر بایگانی موجودی از طریق
.Cm @@ Ns Ar archive-name
رونوشت شود، مقداری پهنای باند شبکه در حین خواندن فراداده‌های
.Ar archive-name
توسط
.Nm
از کارساز tarsnap مصرف خواهد شد.
.Pp
علاوه بر این،
.Fl -dry-run
بررسی نخواهد کرد که آیا دایرکتوری حافظهٔ پنهان ناهمگام شده است یا خیر.
.It Fl -dry-run-metadata
(تنها در حالت c)
بایگانی را واقعاً ایجاد نمی‌کند؛ تنها انجام این کار را شبیه‌سازی می‌کند.
این گزینه مشابه
.Fl -dry-run
است، با این تفاوت که هیچ فایلی را نمی‌خواند و تنها فراداده‌های سیستم‌فایل را پردازش می‌کند.
.Pp
این روش به مراتب سریع‌تر از یک
.Fl -dry-run
عادی است، اما همچنان برای بررسی این‌که کدام مدخل‌های سیستم‌فایل بایگانی خواهند شد (با
.Fl v ) ،
یا به دست آوردن اندازهٔ کل فشرده‌نشدهٔ بایگانی (از طریق
.Fl -totals
یا
.Fl -progress-bytes )
مناسب است.
.Pp
این گزینه نمی‌تواند همراه با
.Fl -print-stats
استفاده شود.
.It Fl -dump-config
چاپ خط فرمان و تمامی خطوط غیرخالی خوانده‌شده از فایل‌های پیکربندی.
.It Fl -exclude Ar pattern
(تنها در حالت‌های c، x و t)
عدم پردازش فایل‌ها یا دایرکتوری‌هایی که با الگوی مشخص‌شده مطابقت دارند.
توجه داشته باشید که استثناها بر الگوها یا نام فایل‌های مشخص‌شده در خط فرمان اولویت دارند.
.It Fl f Ar archive-name
(تنها در حالت‌های c، d، x، t، r، list-archives و print-stats)
عملیات بر روی بایگانی
.Ar archive-name .
در حالت c، اگر ایجاد بایگانی با \&^Q،
سیگنال SIGQUIT، یا رسیدن به محدودیت پهنای باند مشخص‌شده از طریق گزینهٔ
.Fl -maxbw
متوقف شود، بایگانی با افزودن ".part" به نام آن ذخیره خواهد شد.
در حالت print-stats، اگر
.Ar archive-name
برابر * باشد، آمار برای هر بایگانی چاپ خواهد شد.
در حالت‌های print-stats و d،
.Fl f Ar archive-name
می‌تواند چندین بار مشخص شود، که در این صورت عملیات (چاپ آمارها یا حذف) برای هر یک از بایگانی‌های مشخص‌شده انجام خواهد گرفت.
.Pp
توجه داشته باشید که هر بایگانی ایجادشده باید نام متفاوتی داشته باشد؛ در نتیجه بسیاری از کاربران هنگام ایجاد مکرر بایگانی‌ها از همان فایل‌ها/دایرکتوری‌ها (مانند پشتیبان‌گیری‌های روزانه)، گنجاندن برچسب‌های زمانی در نام بایگانی را مفید می‌دانند.
.Pp
به عنوان یک مورد خاص، اگر با
.Fl -list-archives -hashes
استفاده شود، آن‌گاه
.Fl f
به جای
.Ar archive-name
نشان‌دهندهٔ یک
.Ar tapehash
خواهد بود، و فراداده‌های مربوط به بایگانی(های) مشخص‌شده را چاپ می‌کند.
این ترکیب از گزینه‌ها برای رابط کاربری گرافیکی در نظر گرفته شده و برای استفاده در خط فرمان نیازی به آن نیست.
.Po
گزینهٔ
.Fl f
نمی‌تواند همراه با
.Fl -list-archives
استفاده شود مگر آن‌که شامل
.Fl -hashes
نیز باشد.
.Pc
.It Fl -force-resources
اجبار رمزگشایی فایل کلید رمزشده با عبارت عبور (passphrase)، حتی اگر پیش‌بینی شود که به مقدار زیادی حافظه یا زمان پردازنده (CPU) نیاز دارد.
.It Fl H
(تنها در حالت c)
پیوندهای نمادین نام‌برده‌شده در خط فرمان دنبال خواهند شد؛ هدف پیوند بایگانی می‌شود، نه خودِ پیوند.
.It Fl h
(تنها در حالت c)
مترادفی برای
.Fl L .
.It Fl -hashes
(تنها در حالت list-archives)
چاپ هش‌های نام‌های بایگانی.
اگر پرچم
.Fl v
یک یا چند بار مشخص شود، نام بایگانی نیز چاپ می‌شود.
.Pp
این گزینه برای رابط کاربری گرافیکی در نظر گرفته شده و برای استفاده در خط فرمان نیازی به آن نیست.
.It Fl -humanize-numbers
استفاده از پیشوندهای SI برای خواناتر کردن اعداد چاپ‌شده توسط
.Fl -print-stats
و SIGINFO.
.It Fl I
مترادفی برای
.Fl T .
.It Fl -include Ar pattern
(تنها در حالت‌های c، x و t)
تنها پردازش فایل‌ها یا دایرکتوری‌هایی که با الگوی مشخص‌شده مطابقت دارند.
توجه داشته باشید که استثناهای مشخص‌شده با
.Fl -exclude
بر موارد شمول اولویت دارند.
اگر هیچ شمولاتی به‌طور صریح مشخص نشده باشد، تمام مدخل‌ها به‌طور پیش‌فرض پردازش می‌شوند.
گزینهٔ
.Fl -include
به ویژه هنگام پالایش بایگانی‌ها مفید است.
برای مثال، دستور
.Dl Nm Fl c Fl f Ar foo-backup Fl -include=\(aq*foo*\(aq Cm @@ Ns Ar all-backup
یک بایگانی جدید
.Ar foo-backup
ایجاد می‌کند که تنها شامل مدخل‌هایی از
.Ar all-backup
است که رشتهٔ
.Sq foo
را در بر دارند.
.It Fl -insane-filesystems
(تنها در حالت c)
اجازهٔ ورود به سیستم‌فایل‌های ساختگی مانند procfs.
به‌طور معمول بایگانی کردن چنین سیستم‌فایل‌هایی کار بیهوده‌ای است، به همین دلیل این نام برای گزینه انتخاب شده است.
.It Fl -iso-dates
(تنها در حالت t)
چاپ تاریخ فایل‌ها و دایرکتوری‌ها به صورت yyyy-mm-dd hh:mm:ss.
.Pp
حالت پیش‌فرض استفاده از همان قالب \(lqls -l\(rq است: اگر فایل‌ها در طول شش ماه گذشته تغییر یافته باشند، ماه، روز، ساعت و دقیقه چاپ می‌شود؛ در غیر این صورت، ماه، روز و سال چاپ می‌گردد.
.It Fl k
(تنها در حالت x)
عدم بازنویسی فایل‌های موجود.
به ویژه، اگر یک فایل بیش از یک بار در یک بایگانی ظاهر شود، نسخه‌های بعدی روی نسخه‌های پیشین بازنویسی نخواهند شد.
.It Fl -keep-going
(تنها در حالت‌های d و print-stats)
ادامه دادن حذف یا چاپ آمارها پس از پی بردن به این‌که یکی از بایگانی‌های مشخص‌شده وجود ندارد.
.It Fl -keep-newer-files
(تنها در حالت x)
عدم بازنویسی فایل‌های موجودی که از نسخه‌های موجود در بایگانی در حال استخراج، تازه‌تر هستند.
.It Fl -keyfile Pa key-file
(همهٔ حالت‌ها)
دریافت کلیدهای رمزنگاری، اصالت‌سنجی و دسترسی از
.Ar key-file .
این فایل باید توسط
.Xr tarsnap-keygen 1
ایجاد شده باشد.
.It Fl L
(تنها در حالت c)
تمامی پیوندهای نمادین دنبال خواهند شد.
به‌طور معمول، پیوندهای نمادین همان‌گونه که هستند بایگانی می‌شوند.
با این گزینه، هدف پیوند به جای آن بایگانی خواهد شد.
.It Fl l
این گزینه مترادفی برای
.Fl -check-links
است.
.It Fl -lowmem
(تنها در حالت c)
کاهش مصرف حافظه با عدم پنهان‌سازی فایل‌های کوچک.
این گزینه ممکن است هنگام پشتیبان‌گیری از فایل‌هایی با میانگین اندازهٔ کمتر از ۱ مگابایت، در صورتی که رم در دسترس به کیلوبایت کمتر از تعداد فایل‌های در حال پشتیبان‌گیری باشد، مفید باشد.
.It Fl m
(تنها در حالت x)
زمان تغییر (modification time) را استخراج نمی‌کند.
به‌طور پیش‌فرض، زمان تغییر بر روی زمان ذخیره‌شده در بایگانی تنظیم می‌شود.
.It Fl -maxbw Ar numbytes
(تنها در حالت c)
در صورتی که بیش از
.Ar numbytes
بایت از پهنای باند بارگذاری (upstream) استفاده شود، فرآیند بایگانی‌سازی را متوقف می‌کند (برای جزئیات بیشتر بخش «قطع فرآیند بایگانی‌سازی (INTERRUPTING ARCHIVAL)» را در زیر ببینید).
.It Fl -maxbw-rate Ar bytespersecond
محدود کردن پهنای باند مصرفی بارگیری و بارگذاری به
.Ar bytespersecond
بایت بر ثانیه.
.It Fl -maxbw-rate-down Ar bytespersecond
محدود کردن پهنای باند مصرفی بارگیری به
.Ar bytespersecond
بایت بر ثانیه.
.It Fl -maxbw-rate-up Ar bytespersecond
محدود کردن پهنای باند مصرفی بارگذاری به
.Ar bytespersecond
بایت بر ثانیه.
.It Fl n
(تنها در حالت c)
محتویات دایرکتوری‌ها را به‌صورت بازگشتی بایگانی نمی‌کند.
.It Fl -newer Ar date
(تنها در حالت‌های c، x و t)
تنها شامل فایل‌ها و دایرکتوری‌های تازه‌تر از تاریخ مشخص‌شده.
این گزینه مدخل‌های ctime را مقایسه می‌کند.
.It Fl -newer-mtime Ar date
(تنها در حالت c)
مشابه
.Fl -newer ،
با این تفاوت که به جای مدخل‌های ctime، مدخل‌های mtime را مقایسه می‌کند.
.It Fl -newer-than Pa filename
(تنها در حالت c)
تنها شامل فایل‌ها و دایرکتوری‌های تازه‌تر از فایل مشخص‌شده.
این گزینه مدخل‌های ctime را مقایسه می‌کند.
.It Fl -newer-mtime-than Pa filename
(تنها در حالت c)
مشابه
.Fl -newer-than ،
با این تفاوت که به جای مدخل‌های ctime، مدخل‌های mtime را مقایسه می‌کند.
.It Fl -no-aggressive-networking
نادیده گرفتن هرگونه گزینهٔ
.Cm aggressive-networking
مشخص‌شده در یک فایل پیکربندی.
.It Fl -no-config-exclude
نادیده گرفتن هرگونه گزینهٔ
.Cm exclude
مشخص‌شده در یک فایل پیکربندی.
به‌طور معمول، گزینه‌های
.Cm exclude
مشخص‌شده از طریق فایل‌های پیکربندی و خط فرمان همگی اعمال می‌شوند.
.It Fl -no-config-include
نادیده گرفتن هرگونه گزینهٔ
.Cm include
مشخص‌شده در یک فایل پیکربندی.
به‌طور معمول، گزینه‌های
.Cm include
مشخص‌شده از طریق فایل‌های پیکربندی و خط فرمان همگی اعمال می‌شوند.
.It Fl -no-default-config
عدم خواندن فایل‌های پیکربندی پیش‌فرض
.Pa /etc/tarsnap/tarsnap.conf ،
.Pa $XDG_CONFIG_HOME/tarsnap/tarsnap.conf
و
.Pa ~/.tarsnaprc .
.It Fl -no-disk-pause
نادیده گرفتن هرگونه گزینهٔ
.Cm disk-pause
مشخص‌شده در یک فایل پیکربندی.
.It Fl -no-force-resources
نادیده گرفتن هرگونه گزینهٔ
.Cm force-resources
مشخص‌شده در یک فایل پیکربندی.
.It Fl -no-humanize-numbers
نادیده گرفتن هرگونه گزینهٔ
.Cm humanize-numbers
مشخص‌شده در یک فایل پیکربندی.
.It Fl -no-insane-filesystems
نادیده گرفتن هرگونه گزینهٔ
.Cm insane-filesystems
مشخص‌شده در یک فایل پیکربندی.
.It Fl -no-iso-dates
نادیده گرفتن هرگونه گزینهٔ
.Cm iso-dates
مشخص‌شده در یک فایل پیکربندی.
.It Fl -no-maxbw
نادیده گرفتن هرگونه گزینهٔ
.Cm maxbw
مشخص‌شده در یک فایل پیکربندی.
.It Fl -no-maxbw-rate-down
نادیده گرفتن هرگونه گزینهٔ
.Cm maxbw-rate-down
مشخص‌شده در یک فایل پیکربندی.
اگر گزینهٔ
.Cm maxbw-rate
در یک فایل پیکربندی مشخص شده باشد، بر پهنای باند بارگیری مصرفی تأثیری نخواهد گذاشت، اما ممکن است بر پهنای باند بارگذاری تأثیر بگذارد (مگر اینکه
.Fl -no-maxbw-rate-up
نیز مشخص شده باشد).
.It Fl -no-maxbw-rate-up
نادیده گرفتن هرگونه گزینهٔ
.Cm maxbw-rate-up
مشخص‌شده در یک فایل پیکربندی.
اگر گزینهٔ
.Cm maxbw-rate
در یک فایل پیکربندی مشخص شده باشد، بر پهنای باند بارگذاری مصرفی تأثیری نخواهد گذاشت، اما ممکن است بر پهنای باند بارگیری تأثیر بگذارد (مگر اینکه
.Fl -no-maxbw-rate-down
نیز مشخص شده باشد).
.It Fl -no-noatime
نادیده گرفتن هرگونه گزینهٔ
.Cm noatime
مشخص‌شده در یک فایل پیکربندی.
.It Fl -no-nodump
نادیده گرفتن هرگونه گزینهٔ
.Cm nodump
مشخص‌شده در یک فایل پیکربندی.
.It Fl -no-print-stats
نادیده گرفتن هرگونه گزینهٔ
.Cm print-stats
مشخص‌شده در یک فایل پیکربندی.
.It Fl -no-progress-bytes
نادیده گرفتن هرگونه گزینهٔ
.Cm progress-bytes
مشخص‌شده در یک فایل پیکربندی.
.It Fl -no-quiet
نادیده گرفتن هرگونه گزینهٔ
.Cm quiet
مشخص‌شده در یک فایل پیکربندی.
.It Fl -no-retry-forever
نادیده گرفتن هرگونه گزینهٔ
.Cm retry-forever
مشخص‌شده در یک فایل پیکربندی.
.It Fl -no-snaptime
نادیده گرفتن هرگونه گزینهٔ
.Cm snaptime
مشخص‌شده در یک فایل پیکربندی.
.It Fl -no-store-atime
نادیده گرفتن هرگونه گزینهٔ
.Cm store-atime
مشخص‌شده در یک فایل پیکربندی.
.It Fl -no-totals
نادیده گرفتن هرگونه گزینهٔ
.Cm totals
مشخص‌شده در یک فایل پیکربندی.
.It Fl -noatime
(تنها در حالت c)
درخواست از سیستم‌عامل برای به‌روزرسانی نکردن atime هنگام خواندن فایل‌ها یا دایرکتوری‌ها. توسط همهٔ سیستم‌عامل‌ها و سیستم‌فایل‌ها پشتیبانی نمی‌شود.
.It Fl -nodump
(تنها در حالت c)
احترام به پرچم فایلی nodump با صرف‌نظر کردن از این فایل یا دایرکتوری.
.It Fl -noisy-warnings
پُرگویی هنگام هشدار دربارهٔ اختلالات شبکه.
این گزینه احتمالاً تنها برای مقاصد اشکال‌زدایی مفید است.
.It Fl -normalmem
نادیده گرفتن هرگونه گزینهٔ
.Cm lowmem
یا
.Cm verylowmem
مشخص‌شده در یک فایل پیکربندی.
.It Fl -null
(استفاده به همراه
.Fl I ،
.Fl T
یا
.Fl X )
مترادفی برای
.Fl -null-input .
به دلایل تاریخی و سازگاری با سایر ابزارهای tar حفظ شده است.
.It Fl -null-input
(استفاده به همراه
.Fl I ،
.Fl T
یا
.Fl X )
نام فایل‌ها، نام‌های بایگانی و الگوها با نویسه‌های null جدا می‌شوند، نه با خطوط جدید.
این گزینه اغلب برای خواندن نام فایل‌های تولیدشده توسط گزینهٔ
.Fl print0
در
.Xr find 1
استفاده می‌شود.
.It Fl -null-output
(تنها در حالت‌های x، t، list-archives و print-stats)
نام‌های بایگانی، نام فایل‌ها و خطوط در خروجی با نویسه‌های null جدا می‌شوند، نه با خطوط جدید.
.Pp
اگر چندین فیلد در یک خط وجود داشته باشد، با دو نویسهٔ null از یکدیگر جدا خواهند شد.
اگر یک خط فرمان در یکی از این فیلدها چاپ شود، هر آرگومان با سه نویسهٔ null جدا خواهد شد.
.It Fl -numeric-owner
(تنها در حالت x)
نادیده گرفتن نام‌های نمادین کاربر و گروه هنگام بازیابی بایگانی‌ها بر روی دیسک؛ تنها مقادیر عددی uid و gid رعایت خواهند شد.
.It Fl O
(تنها در حالت‌های x و t)
در حالت استخراج (x\-)، فایل‌ها به جای استخراج روی دیسک، در خروجی استاندارد نوشته می‌شوند.
در حالت فهرست‌گیری (t\-)، فهرست فایل‌ها به جای خروجی استاندارد معمول، در stderr نوشته خواهد شد.
.It Fl o
(تنها در حالت x)
استفاده از کاربر و گروهِ کاربری که برنامه را اجرا می‌کند، به جای موارد مشخص‌شده در بایگانی.
توجه داشته باشید که این گزینه هیچ تأثیری ندارد مگر آن‌که
.Fl p
مشخص شده باشد و برنامه توسط کاربر ریشه (root) اجرا شود.
در این حالت، حالت‌ها و پرچم‌های فایل از بایگانی بازیابی خواهند شد، اما ACLها یا اطلاعات مالک در بایگانی نادیده گرفته می‌شوند.
.It Fl -one-file-system
(تنها در حالت c)
از نقاط اتصال (mount points) عبور نمی‌کند.
.It Fl P
(تنها در حالت‌های c، x و t)
حفظ نام مسیرها.
به‌طور پیش‌فرض، نام مسیرهای مطلق (آن‌هایی که با نویسهٔ / آغاز می‌شوند) هم هنگام ایجاد بایگانی و هم هنگام استخراج از آن، اسلش ابتدایی‌شان حذف می‌شود.
همچنین،
.Nm
از استخراج مدخل‌های بایگانی که نام مسیر آن‌ها شامل
.Pa ..
باشد یا دایرکتوری مقصد آن‌ها توسط یک پیوند نمادین دستخوش تغییر شود، خودداری می‌کند.
این گزینه این رفتارها را لغو می‌کند.
.It Fl p
(تنها در حالت x)
حفظ مجوزهای فایل.
تلاش برای بازیابی کامل مجوزها از جمله مالک، حالت‌های فایل، پرچم‌های فایل و ACLها (در صورت موجود بودن) برای هر مورد استخراج‌شده از بایگانی.
به‌طور پیش‌فرض، مالک فایل‌های تازه‌ساخته‌شده کاربری است که
.Nm
را اجرا می‌کند، حالت فایل برای فایل‌های عادیِ تازه‌ساخته‌شده بازیابی می‌شود، و سایر انواع مدخل‌ها مجوزهای پیش‌فرض را دریافت می‌کنند.
اگر
.Nm
توسط ریشه (root) اجرا شود، حالت پیش‌فرض بازیابی مالک است، مگر اینکه گزینهٔ
.Fl o
نیز مشخص شده باشد.
.It Fl -passphrase Ar method:arg
خواندن عبارت عبور (passphrase) با استفاده از روش مشخص‌شده.
.Bl -tag -width aa
.It Ar dev:tty-stdin
تلاش برای خواندن عبارت عبور از dev/tty/؛ در صورت شکست، خواندن آن از stdin.
این رفتار پیش‌فرض است.
.It Ar dev:stdin-once
تلاش برای خواندن عبارت عبور از stdin، و انجام آن تنها برای یک بار حتی هنگام رمزنگاری.
اگر
.Ar infile
نیز stdin باشد (یا همان \(aq-\(aq)، این گزینه قابل استفاده نیست.
.It Ar dev:tty-once
تلاش برای خواندن عبارت عبور از dev/tty/، و انجام آن تنها برای یک بار حتی هنگام رمزنگاری.
.It Ar env:VAR
خواندن عبارت عبور از متغیر محیطی مشخص‌شده توسط
.Ar VAR .
.Pp
.Bf Em
ذخیرهٔ عبارت عبور در یک متغیر محیطی ممکن است یک خطر امنیتی باشد.
.Ef
تنها در صورتی از این گزینه استفاده کنید که مطمئن باشید می‌دانید چه کاری انجام می‌دهید.
.It Ar file:FILENAME
خواندن عبارت عبور از فایل مشخص‌شده توسط
.Ar FILENAME .
.Pp
.Bf Em
ذخیرهٔ عبارت عبور در یک فایل ممکن است یک خطر امنیتی باشد.
.Ef
تنها در صورتی از این گزینه استفاده کنید که مطمئن باشید می‌دانید چه کاری انجام می‌دهید.
.El
.It Fl -print-stats
(تنها در حالت‌های c و d)
چاپ آمار برای بایگانی در حال ایجاد (حالت c) یا حذف (حالت d).
برای اطلاعات دربارهٔ قالب خروجی، بخش «چاپ آمار بایگانی (PRINTING ARCHIVE STATISTICS)» را در زیر ببینید.
.It Fl -progress-bytes Ar X
نمایش یک پیام پیشرفت (مشابه آنچه از SIGUSR1 یا SIGINFO تولید می‌شود) پس از پردازش هر
.Ar X
بایت.
حداکثر یک بار برای هر فایل رخ می‌دهد.
.It Fl q ( Fl -fast-read )
(تنها در حالت‌های x و t)
تنها استخراج یا فهرست‌گیری از نخستین مدخل بایگانی که با هر الگو یا عملوندِ نام فایل مطابقت دارد.
به محض این‌که هر الگو یا نام فایل مشخص‌شده مطابقت یافت، خارج می‌شود.
به‌طور پیش‌فرض، بایگانی همیشه تا انتها خوانده می‌شود، چرا که ممکن است چندین مدخل با نام یکسان وجود داشته باشند و بر حسب قرارداد، مدخل‌های بعدی بر روی مدخل‌های قبلی بازنویسی می‌شوند.
این گزینه به عنوان یک بهینه‌سازی کارایی ارائه شده است.
.It Fl -quiet
اجتناب از چاپ برخی هشدارها.
در حال حاضر هشدارهایی که توسط این گزینه بی‌صدا می‌شوند عبارتند از:
"Removing leading '/' ..."،
"Not adding cache directory to archive"،
"... file may have grown while being archived"
و
"Skipping entry on filesystem of type ..."؛
اما این احتمال وجود دارد که هشدارهای دیگری نیز در نسخه‌های آیندهٔ
.Nm
توسط این گزینه بی‌صدا شوند.
.It Fl -resume-extract
(تنها در حالت x)
عدم استخراج فایل‌هایی که اندازهٔ فایل و mtime آن‌ها با فایل‌های موجود روی دیسک مطابقت دارد.
در درجهٔ اول برای از سر گرفتن فرآیند استخراج بایگانی که متوقف شده بود استفاده می‌شود.
مقایسهٔ mtime از دقت زمانی زیر ثانیه چشم‌پوشی می‌کند، زیرا این مورد در همهٔ سیستم‌فایل‌ها پشتیبانی نمی‌شود.
این گزینه با
.Fl k
تفاوت دارد، زیرا
.Fl -resume-extract
در صورتی که اندازه یا زمان تغییر مطابقت نداشته باشد، فایل را بازنویسی خواهد کرد؛ همان‌طور که اگر tarsnap در حین استخراج یک فایل متوقف شود رخ می‌دهد.
.It Fl -retry-forever
این گزینه باعث می‌شود tarsnap به جای تسلیم شدن پس از ۵ تا ۱۰ دقیقه، به تلاش بی‌پایان برای اتصال مجدد به کارساز tarsnap ادامه دهد.
این گزینه ممکن است برای کاربرانی با شبکه‌های به شدت ناپایدار، یا روی دستگاه‌های تلفن همراه که به‌طور منظم اتصال اینترنت خود را برای مدت‌های طولانی از دست می‌دهند مفید باشد.
این گزینه به‌طور پیش‌فرض فعال نیست، زیرا شکست‌های مداوم عموماً نشان‌دهندهٔ مشکلی هستند که باید توسط کاربر بررسی شود.
.It Fl S
(تنها در حالت x)
استخراج فایل‌ها به‌صورت فایل‌های تنک (sparse files).
به ازای هر بلوک روی دیسک، ابتدا بررسی می‌کند که آیا شامل بایت‌های غیر تهی (non-NULL) است یا خیر، و در غیر این صورت از روی آن می‌پرد (seek over).
عملکرد این گزینه مشابه گزینهٔ conv=sparse در dd است.
.It Fl s Ar pattern
تغییر نام فایل یا اعضای بایگانی بر اساس
.Pa pattern .
این الگو دارای ساختار /old/new/[gps] است.
عبارت old یک عبارت باقاعدهٔ پایه (basic regular expression) است.
اگر اعمال نشود، از الگو صرف‌نظر می‌شود.
عبارت new رشتهٔ جایگزین برای بخش تطبیق‌یافته است.
نویسهٔ ~ با بخش تطبیق‌یافته، و \e1 تا \e9 با محتویات گروه ثبت‌شدهٔ متناظر جایگزین می‌شوند.
نویسهٔ اختیاری انتهایی g مشخص می‌کند که تطبیق باید پس از بخش منطبق ادامه یابد و با نخستین الگوی منطبق‌نشده متوقف شود.
نویسهٔ اختیاری انتهایی s مشخص می‌کند که الگو بر روی مقدار پیوندهای نمادین اعمال شود.
نویسهٔ اختیاری انتهایی p مشخص می‌کند که پس از یک جایگزینی موفق، نام مسیر اصلی و نام مسیر جدید در خطای استاندارد (stderr) چاپ شوند.
.It Fl -snaptime Pa filename
(تنها در حالت c)
این گزینه هنگام ایجاد پشتیبان از یک تصویر لحظه‌ای سیستم‌فایل (filesystem snapshot) الزامی است، و
.Pa filename
باید دارای زمان تغییری قبل از زمان ایجاد تصویر لحظه‌ای سیستم‌فایل باشد.
(این کار برای جلوگیری از شرایط رقابتی میان تغییر فایل و ایجاد تصویر لحظه‌ای ضروری است که می‌تواند منجر به عدم تشخیص تغییر فایل توسط
.Nm
شود.)
.It Fl -store-atime
(تنها در حالت c)
فعال‌سازی ذخیرهٔ زمان‌های دسترسی فایل (atime).
رفتار پیش‌فرض
.Nm
این است که زمان‌های دسترسی فایل را ذخیره نکند، زیرا وقتی یک مجموعه فایل چندین بار بایگانی می‌شوند (مثلاً در صورت ایجاد بایگانی‌های پشتیبان روزانه)، به دلیل این‌که خودِ
.Nm
به فایل‌ها دسترسی پیدا کرده و موجب تغییر زمان دسترسی آن‌ها می‌شود، می‌تواند منجر به هدررفت بخش قابل توجهی از پهنای باند و فضای ذخیره‌سازی گردد.
.It Fl -strip-components Ar count
(تنها در حالت x)
حذف تعداد مشخص‌شده از اجزای ابتدایی مسیر.
نام مسیرهایی با اجزای کمتر بدون هیچ هشداری نادیده گرفته می‌شوند.
توجه داشته باشید که نام مسیر پس از بررسی الگوهای شمول/استثنا اما پیش از بررسی‌های امنیتی ویرایش می‌شود.
.It Fl T Ar filename
(تنها در حالت‌های c، x و t)
در حالت x یا t، برنامهٔ
.Nm
فهرست نام‌های قابل استخراج را از
.Pa filename
می‌خواند.
در حالت c، برنامهٔ
.Nm
نام‌های قابل بایگانی را از
.Pa filename
می‌خواند.
نام خاص
.Dq -C
در یک خط مستقل موجب می‌شود دایرکتوری جاری به دایرکتوری مشخص‌شده در خط بعدی تغییر یابد.
نام‌ها با خطوط جدید خاتمه می‌یابند مگر آن‌که
.Fl -null-input
مشخص شده باشد.
توجه داشته باشید که
.Fl -null-input
همچنین پردازش ویژهٔ خطوط حاوی
.Dq -C
را غیرفعال می‌کند.
اگر
.Pa filename
برابر
.Dq -
باشد، فهرست نام‌ها از ورودی استاندارد خوانده خواهد شد.
نکته: اگر فهرست فایل‌ها را با استفاده از
.Xr find 1
تولید می‌کنید، احتمالاً مایل خواهید بود از
.Fl n
نیز استفاده کنید.
.It Fl -totals
(تنها در حالت c)
چاپ اندازهٔ بایگانی پس از ایجاد آن.
این گزینه عمدتاً برای سازگاری با GNU tar ارائه شده است؛ در بیشتر شرایط گزینهٔ
.Fl -print-stats
بسیار مفیدتر خواهد بود.
.It Fl U
(تنها در حالت x)
قطع پیوند فایل‌ها (unlink) پیش از ایجاد آن‌ها.
بدون این گزینه،
.Nm
فایل‌های موجود را بازنویسی می‌کند که این کار پیوندهای سخت (hardlinks) موجود را حفظ می‌کند.
با این گزینه، پیوندهای سخت موجود، و همچنین هر پیوند نمادینی که بر مکان یک فایل استخراج‌شده تأثیر بگذارد، شکسته خواهند شد.
.It Fl v
(تنها در حالت‌های c، d، t، x و list-archives)
تولید خروجی پرگو (verbose).
در حالت‌های ایجاد و استخراج،
.Nm
نام هر فایل را هنگام خوانده شدن از بایگانی یا نوشته شدن در آن فهرست می‌کند.
در حالت حذف،
.Nm
نام هر بایگانی را هنگام حذف شدن فهرست می‌کند.
در حالت فهرست‌گیری،
.Nm
خروجی مشابهی با
.Xr ls 1
تولید خواهد کرد.
گزینه‌های
.Fl v
بیشتر جزئیات بیشتری ارائه خواهند داد.
.It Fl -verify-config
بررسی خطاهای ساختاری در فایل(های) پیکربندی.
.It Fl -version
چاپ شماره نسخهٔ
.Nm
و خروج.
.It Fl -verylowmem
(تنها در حالت c)
کاهش مصرف حافظه، تقریباً به میزان دو برابر بیشتر از کاهش مصرف حافظه هنگام مشخص شدن
.Fl -lowmem ،
با پنهان‌سازی نکردن هیچ‌چیز.
.It Fl w
(تنها در حالت‌های c و x)
درخواست تایید برای هر اقدام.
.It Fl X Ar filename
(تنها در حالت‌های c، x و t)
خواندن فهرستی از الگوهای استثنا از فایل مشخص‌شده.
برای اطلاعات بیشتر دربارهٔ نحوهٔ مدیریت استثناها،
.Fl -exclude
را ببینید.
.El
.Sh "سیگنال‌ها (SIGNALS)"
برنامهٔ
.Nm
سیگنال‌های زیر را مدیریت می‌کند:
.Bl -tag -width "SIGUSR2"
.It SIGUSR1 و SIGINFO
با دریافت سیگنال SIGUSR1 یا (در بسترهایی که وجود دارد) سیگنال SIGINFO،
برنامهٔ
.Nm
فایل یا دایرکتوری در حال پردازش و (برای فایل‌ها) میزان پیشرفت درون آن فایل را چاپ می‌کند.
همچنین تعداد فایل‌ها و تعداد بایت‌های فشرده‌نشدهٔ پردازش‌شده را چاپ می‌کند.
توجه داشته باشید که به دلیل میان‌گیرسازی (buffering) شبکه، موقعیت فایل ممکن است دقیقاً با میزان داده‌های ارسال‌شده یا دریافت‌شده از کارساز
.Nm
هم‌تراز نباشد.
.It SIGSTOP و SIGTSTP
با دریافت سیگنال SIGSTOP یا SIGTSTP، هسته پردازش
.Nm
را معلق می‌کند.
با دریافت سیگنال SIGCONT، برنامهٔ
.Nm
مجدداً به کارساز متصل شده (در صورت نیاز) و وظیفهٔ مشخص‌شده را ادامه می‌دهد.
.It SIGUSR2
با دریافت سیگنال SIGUSR2، اگر
.Nm
در حال ایجاد یک بایگانی باشد (حالت c)، یک نقطهٔ بازبینی (checkpoint) در موقعیت فعلی ایجاد می‌کند.
.It SIGQUIT
با دریافت سیگنال SIGQUIT، اگر
.Nm
در حال ایجاد یک بایگانی باشد (حالت c)، بایگانی را در موقعیت فعلی کوتاه کرده (truncate) و خارج می‌شود (بخش «قطع فرآیند بایگانی‌سازی (INTERRUPTING ARCHIVAL)» را در زیر ببینید).
.El
.Sh "چاپ آمار بایگانی (PRINTING ARCHIVE STATISTICS)"
چهار دستور وجود دارند که آمارهای مربوط به بایگانی‌ها را چاپ می‌کنند:
.Bl -bullet -width indent
.It
آمارهای سراسری:
.Dl Nm Fl -print-stats
.It
آمارهای سراسری و اطلاعات دربارهٔ بایگانی(های) خاص:
.Dl Nm Fl -print-stats Fl f Ar archive-name1 Op Fl f Ar ...
.It
آمارهای سراسری و اطلاعات دربارهٔ تمامی بایگانی‌ها:
.Dl Nm Fl -print-stats Fl f Ar \(aq*\(aq
.It
آمارهای سراسری و اطلاعات دربارهٔ بایگانی(هایی) که تازه ایجاد یا حذف شده‌اند:
.Dl Nm Fl c Fl -print-stats Fl f Ar archive-name Ar DIR
.Dl Nm Fl d Fl -print-stats Fl f Ar archive-name1 Op Fl f Ar ...
.El
.Pp
برنامهٔ
.Nm
جدولی به قالب زیر را چاپ خواهد کرد:
.Bd -literal
                                       Total size  Compressed size
All archives                         104491640436      51510524844
  (unique data)                       14830618089       7733620463
This archive                            808723344        289077325
New data                                 17858641          5658308
.Ed
.Pp
در این مثال، مجموع اندازهٔ تمامی بایگانی‌های ذخیره‌شده توسط
.Nm
با استفاده از کلیدهای یکسان برابر ۱۰۴ گیگابایت است، و مجموع اندازه پس از فشرده‌سازی ۵۱ گیگابایت خواهد بود؛ اما پس از حذف بلوک‌های تکراری، تنها ۱۴٫۸ گیگابایت باقی می‌ماند که با فشرده‌سازی به ۷٫۷ گیگابایت می‌رسد.
(همین ۷٫۷ گیگابایت است که از طریق سرویس Tarsnap ذخیره شده و در نتیجه باید بابت آن هزینه پرداخت شود.)
بایگانی تازه‌ساخته‌شده ۸۰۸ مگابایت اندازه دارد (قابل فشرده‌سازی به ۲۸۹ مگابایت)، اما تنها ۱۷٫۸ مگابایت از داده‌ها جدید است، و پس از فشرده‌سازی تنها ۵٫۶ مگابایت در کارساز Tarsnap بارگذاری می‌شود.
.Pp
هنگامی که
.Nm
.Fl -print-stats
به عنوان یک دستور اجرا می‌شود، جدول در خروجی استاندارد چاپ می‌شود؛
هنگامی که گزینهٔ
.Fl -print-stats
در زمان ایجاد یا حذف بایگانی‌ها استفاده شود، جدول در دستگاه خطای استاندارد (stderr) چاپ می‌شود.
.Pp
آمارهای سراسری بر اساس دایرکتوری حافظهٔ پنهان جاری محاسبه می‌شوند، بدون استفاده از keyfile یا پرس‌وجو از کارسازهای Tarsnap.
.Sh "قطع فرآیند بایگانی‌سازی (INTERRUPTING ARCHIVAL)"
با دریافت سیگنال
.Dv SIGQUIT
یا \&^Q،
یا در صورت رسیدن به محدودیت پهنای باند مشخص‌شده از طریق گزینهٔ
.Fl -maxbw ،
برنامهٔ
.Nm
ایجاد بایگانی را متوقف کرده و آن را در موقعیت فعلی کوتاه (truncate) می‌کند.
هنگامی که یک بایگانی کوتاه می‌شود، بر اساس نام مشخص‌شده توسط کاربر به اضافهٔ ".part" نام‌گذاری خواهد شد تا نشان‌دهندهٔ ناقص بودن آن باشد.
چنین بایگانی کوتاه‌شده‌ای ممکن است به خودی خود مفید باشد، اما این مزیت را نیز به همراه دارد که تلاش‌های آینده برای بایگانی کردن همان داده‌ها سریع‌تر بوده و پهنای باند کمتری مصرف خواهند کرد.
.Sh "دیواره‌های آتش (FIREWALLS)"
برنامهٔ
.Nm
از طریق یک اتصال TCP به درگاه ۹۲۷۹ با کارساز
.Nm
ارتباط برقرار می‌کند؛ در برخی محیط‌ها ممکن است افزودن یک قاعدهٔ دیوارهٔ آتش برای مجاز کردن اتصالات خروجی TCP به این درگاه لازم باشد.
در حال حاضر (ژوئیه ۲۰۰۹) تنها یک نشانی IP برای کارساز
.Nm
استفاده می‌شود، بنابراین مدیران شبکه ممکن است بخواهند آن نشانی IP را به‌طور ثابت تنظیم کنند؛ با این حال، محتمل است که در مقطعی از آینده آن نشانی IP تغییر کرده و/یا نشانی‌های IP دیگری اضافه شوند.
.Sh "محیط (ENVIRONMENT)"
متغیرهای محیطی زیر بر اجرای
.Nm
تأثیر می‌گذارند:
.Bl -tag -width ".Ev BLOCKSIZE"
.It Ev LANG
محلی‌سازی (locale) مورد استفاده.
برای اطلاعات بیشتر
.Xr environ 7
را ببینید.
.It Ev TZ
منطقهٔ زمانی مورد استفاده هنگام نمایش تاریخ‌ها.
برای اطلاعات بیشتر
.Xr environ 7
را ببینید.
.El
.Sh "فایل‌ها (FILES)"
.Bl -tag -width indent
.It Pa /etc/tarsnap/tarsnap.conf
فایل پیکربندی سراسری سیستم برای
.Nm .
پارامترهای مشخص‌شده در اینجا تنها زمانی اعمال می‌شوند که از طریق فایل پیکربندی محلی کاربر جاری یا خط فرمان مشخص نشده باشند.
.It Pa $XDG_CONFIG_HOME/tarsnap/tarsnap.conf
یک فایل پیکربندی
.Nm
برای کاربر جاری.
اگر متغیر محیطی
.Ev XDG_CONFIG_HOME
خالی باشد، مقدار پیش‌فرض
.Pa ~/.config/tarsnap/tarsnap.conf
استفاده خواهد شد.
پارامترهای مشخص‌شده در اینجا اعمال می‌شوند مگر اینکه از طریق
.Pa ~/.tarsnaprc
یا خط فرمان مشخص شده باشند.
.It Pa ~/.tarsnaprc
مکانی دیگر برای فایل پیکربندی
.Nm
برای کاربر جاری.
پارامترهای مشخص‌شده در اینجا اعمال می‌شوند مگر اینکه از طریق خط فرمان مشخص شده باشند.
.El
.Sh "وضعیت خروج (EXIT STATUS)"
.Ex -std
.Pp
کد خروج ۲ نشان‌دهندهٔ این است که خطایی رخ داده و وضعیت سمت کارساز تغییر یافته است.
.Sh "مثال‌ها (EXAMPLES)"
ثبت‌نام در کارساز و تولید کلیدها:
.Dl Nm tarsnap-keygen Fl -keyfile Pa /usr/tarsnap.key Fl -user Ar me@example.com Fl -machine Ar myserver
.Pp
تهیهٔ پشتیبان از
.Pa /usr/home
و
.Pa /other/stuff/to/backup :
.Dl Nm Fl -keyfile Pa /usr/tarsnap.key Fl -cachedir Pa /usr/tarsnap-cache Fl c Fl f Ar backup-2008-04-24 Pa /usr/home Pa /other/stuff/to/backup
.Pp
تهیهٔ یک پشتیبان دیگر، یک روز بعد؛
این کار بسیار سریع‌تر است زیرا tarsnap از ذخیرهٔ مجدد داده‌هایی که قبلاً ذخیره شده‌اند خودداری می‌کند:
.Dl Nm Fl -keyfile Pa /usr/tarsnap.key Fl -cachedir Pa /usr/tarsnap-cache Fl c Fl f Ar backup-2008-04-25 Pa /usr/home Pa /other/stuff/to/backup
.Pp
فهرست کردن بایگانی‌ها:
.Dl Nm Fl -keyfile Pa /usr/tarsnap.key Fl -list-archives
.Pp
حذف نخستین پشتیبان و دست‌نخورده باقی گذاشتن دومین پشتیبان:
.Dl Nm Fl -keyfile Pa /usr/tarsnap.key Fl -cachedir Pa /usr/tarsnap-cache Fl d Fl f Ar backup-2008-04-24
.Pp
فهرست کردن فایل‌های درون پشتیبان باقی‌مانده:
.Dl Nm Fl -keyfile Pa /usr/tarsnap.key Fl tv Fl f Ar backup-2008-04-25
.Pp
بازیابی دایرکتوری خانگی دو کاربر از پشتیبان:
.Dl Nm Fl -keyfile Pa /usr/tarsnap.key Fl x Fl f Ar backup-2008-04-25 Pa usr/home/auser Pa usr/home/anotheruser
.Pp
در
.Pa /etc/crontab
برای ایجاد یک نسخهٔ پشتیبان از کل سیستم در ساعت ۱۰:۳۲ هر روز:
.Dl 32 10 * * * root Nm Fl -keyfile Pa /usr/tarsnap.key Fl -cachedir Pa /usr/tarsnap-cache Fl c Fl f Ar backup-`date +\e%Y\e%m\e%d` Pa /
.Pp
توجه داشته باشید که گزینه‌های
.Fl -keyfile
و
.Fl -cachedir
می‌توانند از طریق فایل پیکربندی
.Xr tarsnap.conf 5
مشخص شوند که در این صورت می‌توان آن‌ها را از خط فرمان حذف کرد.
.Sh "امنیت (SECURITY)"
برخی مسائل امنیتی در بسیاری از برنامه‌های بایگانی‌سازی، از جمله
.Nm
مشترک هستند.
به‌ویژه، بایگانی‌هایی که با دقت دستکاری شده‌اند می‌توانند درخواست کنند که
.Nm
فایل‌ها را در مکان‌هایی خارج از دایرکتوری مقصد استخراج کند.
این مورد می‌تواند به‌طور بالقوه برای وادار کردن کاربران ناآگاه به بازنویسی فایل‌هایی که قصد بازنویسی آن‌ها را نداشته‌اند استفاده شود.
اگر بایگانی توسط مدیر سیستم (superuser) استخراج شود، هر فایلی در سیستم ممکن است بازنویسی شود.
این اتفاق به سه روش می‌تواند رخ دهد.
اگرچه
.Nm
سازوکارهایی برای محافظت در برابر هر یک از آن‌ها دارد، کاربران آگاه باید از پیامدهای آن مطلع باشند:
.Bl -bullet -width indent
.It
مدخل‌های بایگانی می‌توانند نام مسیرهای مطلق داشته باشند.
به‌طور پیش‌فرض،
.Nm
برای محافظت در برابر این مشکل، نویسهٔ
.Pa /
ابتدایی را پیش از بازیابی فایل‌ها از نام آن‌ها حذف می‌کند.
.It
مدخل‌های بایگانی می‌توانند نام مسیرهایی شامل اجزای
.Pa ..
داشته باشند.
به‌طور پیش‌فرض،
.Nm
فایل‌هایی را که نام مسیر آن‌ها شامل اجزای
.Pa ..
باشد استخراج نخواهد کرد.
.It
مدخل‌های بایگانی می‌توانند از پیوندهای نمادین برای بازیابی فایل‌ها در دایرکتوری‌های دیگر سوءاستفاده کنند.
یک بایگانی می‌تواند یک پیوند نمادین به دایرکتوری دیگری را بازیابی کند، سپس از آن پیوند برای بازیابی یک فایل درون آن دایرکتوری استفاده نماید.
برای محافظت در برابر این موضوع،
.Nm
هر مسیر استخراج‌شده را برای پیوندهای نمادین بررسی می‌کند.
اگر جزء نهایی مسیر یک پیوند نمادین باشد، حذف شده و با مدخل بایگانی جایگزین خواهد شد.
اگر
.Fl U
مشخص شده باشد، هر پیوند نمادین میانی نیز بدون قید و شرط حذف خواهد شد.
اگر نه
.Fl U
و نه
.Fl P
مشخص نشده باشند،
.Nm
از استخراج آن مدخل خودداری خواهد کرد.
.El
.Pp
اگرچه
.Nm
بایگانی‌ها را از نظر رمزنگاری به گونه‌ای امضا می‌کند که باور بر این است جعل یک بایگانی برای مهاجم بدون داشتن
.Ar key-file
امکان‌پذیر نیست، اما ممکن است بخواهید پیش از استخراج، محتویات بایگانی(ها) را با دستور
.Dl Nm Fl t Fl -keyfile Ar key-file Fl f Ar archive-name
بررسی کنید.
توجه داشته باشید که گزینهٔ
.Fl P
در
.Nm
بررسی‌های امنیتی فوق را غیرفعال کرده و به شما امکان می‌دهد یک بایگانی را با حفظ هرگونه نام مسیر مطلق، اجزای
.Pa .. ،
یا پیوندهای نمادین به سایر دایرکتوری‌ها استخراج کنید.
.Sh "همچنین ببینید (SEE ALSO)"
.Xr tarsnap-keygen 1 ,
.Xr tar 5 ,
.Xr tarsnap.conf 5
.Sh "تاریخچه (HISTORY)"
دستور
.Nm tar
در نگارش هفتم یونیکس (Seventh Edition Unix) پدیدار شد که در ژانویه ۱۹۷۹ منتشر گردید.
پیاده‌سازی‌های متعدد دیگری نیز وجود داشته‌اند که بسیاری از آن‌ها قالب فایل را گسترش دادند.
پیاده‌سازی مالکیت عمومی
.Nm pdtar
توسط John Gilmore (حدود نوامبر ۱۹۸۷) بسیار تأثیرگذار بود و اساس GNU tar را تشکیل داد.
دستور GNU tar از زمان
.Fx 1.0
به عنوان tar استاندارد سیستم در
.Fx
گنجانده شد، اما در
.Fx 5.3
با ابزار
.Nm bsdtar
و کتابخانهٔ
.Xr libarchive 3
توسط Tim Kientzle جایگزین گردید.
.Pp
برنامهٔ
.Nm
بر پایهٔ
.Nm bsdtar
و
.Xr libarchive 3
ساخته شده است.
.Sh "گزارش باگ‌ها (BUGS)"
این برنامه برای تعریف گزینهٔ
.Fl l
در
.Xr tar 5
از استاندارد
.St -p1003.1-96
پیروی می‌کند.
توجه داشته باشید که GNU tar قبل از نسخهٔ ۱٫۱۵ گزینهٔ
.Fl l
را به عنوان مترادفی برای گزینهٔ
.Fl -one-file-system
در نظر می‌گرفت.
.Pp
برای بایگانی کردن فایلی به نام
.Pa @foo ،
.Pa @@foo
یا
.Pa -foo
باید آن را به ترتیب به صورت
.Pa ./@foo ،
.Pa ./@@foo
یا
.Pa ./-foo
مشخص کنید.
.Pp
در حالت ایجاد، پیشوند
.Pa ./
همیشه حذف می‌شود.
پیشوند
.Pa /
نیز حذف می‌شود مگر اینکه گزینهٔ
.Fl P
مشخص شده باشد.
.Pp
اگر فایل بایگانی اضافه‌شده از طریق گزینهٔ
.Cm @ Ns Pa archive-file
در قالبی غیر از \(lqtar\(rq باشد، ممکن است اطلاعات پیوند سخت از بین برود.
(این امر پیامد روش‌های ناسازگاری است که قالب‌های مختلف بایگانی اطلاعات پیوند سخت را ذخیره می‌کنند.)
.Pp
برای بسیاری از گزینه‌های کوتاه، گزینه‌های بلند جایگزینی وجود دارند که عمداً مستند نشده‌اند.
.Pp
محدودیت مشخص‌شده توسط گزینهٔ
.Fl -maxbw
به‌طور سخت‌گیرانه اعمال نمی‌شود؛
به‌ویژه، به دلیل نیاز به پایان دادن پاکیزه به یک بایگانی، میزان پهنای باند مصرفی ممکن است اندکی از حد مجاز فراتر رود.
.Pp
اگر
.Nm
با ورودی استاندارد، خروجی استاندارد و خطای استاندارد بازهدایت‌شده و درون یک chroot که در آن دستگاه‌های پایانه (terminal devices) در دسترس نیستند اجرا شود، ترکیب \&^Q به SIGQUIT نگاشت نخواهد شد و در نتیجه باعث برش و کوتاه شدن بایگانی جاری نخواهد شد.