borg(1) borg backup tool borg(1)

borg - ابزار پیشرفته پشتیبانگیری با حذف دادههای تکراری و رمزگذاری

borg [گزینه‌های عمومی] <دستور> [گزینه‌ها] [آرگومان‌ها]

نرم‌افزار BorgBackup (به‌طور خلاصه: Borg) یک برنامه پشتیبان‌گیری با حذف داده‌های تکراری است. به‌طور اختیاری، این برنامه از فشرده‌سازی و رمزگذاری احراز هویت‌شده پشتیبانی می‌کند.

هدف اصلی Borg ارائه یک روش کارآمد و امن برای پشتیبان‌گیری از داده‌ها است. فناوری حذف داده‌های تکراری (Deduplication) به‌کار رفته، Borg را برای پشتیبان‌گیری‌های روزانه مناسب می‌سازد، چرا که تنها تغییرات ذخیره می‌شوند. رمزگذاری احراز هویت‌شده نیز آن را برای پشتیبان‌گیری روی مقاصدی که کاملاً قابل اعتماد نیستند مناسب می‌سازد.

برنامه Borg مجموعه‌ای از فایل‌ها را در یک بایگانی (archive) ذخیره می‌کند. یک مخزن (repository) مجموعه‌ای از بایگانی‌ها است. قالب ساختار مخزن‌ها مختص Borg است. Borg بایگانی‌ها را به هیچ روشی جز از طریق نامشان از یکدیگر متمایز نمی‌کند؛ تفاوتی ندارد که بایگانی‌ها در چه زمانی یا در کجا (برای نمونه میزبان‌های گوناگون) ایجاد شده باشند.

1.
پیش از تهیه پشتیبان، ابتدا باید یک مخزن راه‌اندازی (initialize) شود:
$ borg init --encryption=repokey /path/to/repo
2.
پشتیبان‌گیری از دایرکتوری‌های ~/src و ~/Documents در بایگانی‌ای به نام Monday:
$ borg create /path/to/repo::Monday ~/src ~/Documents
3.
روز بعد، ایجاد یک بایگانی جدید به نام Tuesday:
$ borg create --stats /path/to/repo::Tuesday ~/src ~/Documents

این پشتیبان‌گیری بسیار سریع‌تر و با حجم بسیار کمتری انجام خواهد شد، چرا که تنها داده‌های جدیدی که پیش‌تر دیده نشده‌اند ذخیره می‌شوند. گزینه --stats باعث می‌شود Borg آمار بایگانی تازه ایجاد شده مانند میزان داده‌های یکتا (داده‌هایی که با دیگر بایگانی‌ها به اشتراک گذاشته نشده‌اند) را در خروجی نمایش دهد:

------------------------------------------------------------------------------
Archive name: Tuesday
Archive fingerprint: bd31004d58f51ea06ff735d2e5ac49376901b21d58035f8fb05dbf866566e3c2
Time (start): Tue, 2016-02-16 18:15:11
Time (end):   Tue, 2016-02-16 18:15:11
Duration: 0.19 seconds
Number of files: 127
------------------------------------------------------------------------------
                      Original size      Compressed size    Deduplicated size
This archive:                4.16 MB              4.17 MB             26.78 kB
All archives:                8.33 MB              8.34 MB              4.19 MB
                      Unique chunks         Total chunks
Chunk index:                     132                  261
------------------------------------------------------------------------------
4.
فهرست کردن تمام بایگانی‌های موجود در مخزن:
$ borg list /path/to/repo
Monday                               Mon, 2016-02-15 19:14:44
Tuesday                              Tue, 2016-02-16 19:15:11
5.
فهرست کردن محتویات بایگانی Monday:
$ borg list /path/to/repo::Monday
drwxr-xr-x user   group          0 Mon, 2016-02-15 18:22:30 home/user/Documents
-rw-r--r-- user   group       7961 Mon, 2016-02-15 18:22:30 home/user/Documents/Important.doc
...
6.
بازیابی بایگانی Monday از طریق استخراج فایل‌ها نسبت به دایرکتوری جاری:
$ borg extract /path/to/repo::Monday
7.
حذف بایگانی Monday (لطفاً توجه داشته باشید که این عمل فضای دیسک مخزن را آزاد نمی‌کند):
$ borg delete /path/to/repo::Monday
8.
بازیابی فضای دیسک با فشرده‌سازی و جمع‌وجور کردن قطعه‌فایل‌ها (segment files) در مخزن:
$ borg compact /path/to/repo

نکته:

برنامه Borg به‌طور پیش‌فرض در حالت بی‌صدا کار می‌کند (با سطح گزارش‌گیری WARNING کار می‌کند). می‌توانید از گزینه‌هایی مانند --progress یا --list برای دریافت گزارش‌های ویژه در حین اجرای دستور استفاده کنید. همچنین می‌توانید گزینه -v (یا --verbose یا --info) را برای تنظیم سطح گزارش‌گیری روی INFO اضافه کنید تا سایر پیام‌های اطلاعاتی را دریافت کنید.

برنامه Borg تنها دریافت گزینه‌ها (در مثال: -s و --progress) را در سمت چپ یا راست تمامی آرگومان‌های مکانی (در مثال: repo::archive و path) می‌پذیرد، نه در میان آن‌ها:

borg create -s --progress repo::archive path  # خوب و ارجح
borg create repo::archive path -s --progress  # نیز کار می‌کند
borg create -s repo::archive path --progress  # کار می‌کند، اما نازیباست
borg create repo::archive -s --progress path  # نادرست

این امر به دلیل مشکلی در ماژول argparse رخ می‌دهد: https://bugs.python.org/issue15112

سیستم فایل محلی (یا سیستم فایل شبکه‌ای سوارشده به‌صورت محلی):

/path/to/repo - مسیر فایل‌سیستمی به دایرکتوری مخزن، مسیر مطلق

path/to/repo - مسیر فایل‌سیستمی به دایرکتوری مخزن، مسیر نسبی

همچنین مواردی مانند ~/path/to/repo یا ~other/path/to/repo نیز کار می‌کنند (توسط پوسته شما گسترش می‌یابند).

نکته: همچنین می‌توانید پیشوند file:// را به یک مسیر فایل‌سیستم بیفزایید تا قالبی به سبک URL داشته باشد.

مخازن دوردست با دسترسی از طریق ssh (<user@host>):

ssh://user@host:port/path/to/repo - مخزن دوردست، مسیر مطلق، شماره درگاه (port) اختیاری است

user@host:/path/to/repo - مخزن دوردست، مسیر مطلق، نحو منسوخ‌شده

مخازن دوردست با مسیرهای نسبی، نحو به سبک URL همراه با پورت:

ssh://user@host:port/./path/to/repo - مسیر نسبی نسبت به دایرکتوری جاری

ssh://user@host:port/~/path/to/repo - مسیر نسبی نسبت به دایرکتوری خانگی کاربر

ssh://user@host:port/~other/path/to/repo - مسیر نسبی نسبت به دایرکتوری خانگی کاربر دیگر (منسوخ‌شده)

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

user@host:path/to/repo - مسیر نسبی نسبت به دایرکتوری جاری

user@host:~/path/to/repo - مسیر نسبی نسبت به دایرکتوری خانگی کاربر

user@host:~other/path/to/repo - مسیر نسبی نسبت به دایرکتوری خانگی کاربر دیگر

نکته: دادن مقادیر user@host:/./path/to/repo یا user@host:/~/path/to/repo یا user@host:/~other/path/to/repo نیز پشتیبانی می‌شود، اما در اینجا الزامی نیست.

اگر پیوسته به یک نشانی مخزن یکسان نیاز دارید، توصیه می‌شود متغیر محیطی BORG_REPO را برای تنظیم پیش‌فرض نشانی مخزن مقداردهی نمایید:

export BORG_REPO='ssh://user@host:port/path/to/repo'

سپس در شرایطی که تنها به نشانی مخزن نیاز است و می‌خواهید از مقدار پیش‌فرض استفاده کنید، کافی است نشانی مخزن را رها کنید - در این صورت نشانی از BORG_REPO خوانده می‌شود.

هنگامی که نحو دستور مستلزم ارائه یک آرگومان مکانی برای مخزن است، از نحو :: برای مشخص کردن نشانی مخزن استفاده نمایید (برای نمونه borg mount :: /mnt).

بسیاری از دستورها به یک مخزن (تنها نشانی مخزن را وارد کنید، به بالا مراجعه شود) یا مکان یک بایگانی نیاز دارند، که همان نشانی مخزن به همراه ::archive_name در انتهای آن است.

نام بایگانی نباید حاوی نویسه / (اسلش) باشد. برای سادگی، بهتر است از فاصله‌ها یا نویسه‌های دیگری که در پوسته یا سیستم فایل معنای ویژه‌ای دارند نیز خودداری فرمایید (دستور borg mount از نام بایگانی به عنوان نام دایرکتوری استفاده می‌کند).

اگر BORG_REPO را مقداردهی کرده‌اید (به بالا مراجعه کنید) و به تعیین مکان بایگانی نیاز است، از ::archive_name استفاده کنید - در این صورت بخش نشانی مخزن از BORG_REPO خوانده خواهد شد.

برنامه Borg تمام خروجی گزارش‌ها (لاگ‌ها) را به‌طور پیش‌فرض در stderr می‌نویسد. اما لطفاً توجه داشته باشید که نمایش داده شدن چیزی در stderr صرفاً به دلیل حضور در stderr، نشان‌دهنده شرایط خطا نیست. لطفاً برای تشخیص وضعیت خطا، هشدار یا موفقیت، سطوح گزارش‌گیری پیام‌ها و کد خروجی borg را بررسی فرمایید.

اگر می‌خواهید خروجی لاگ را در یک فایل ذخیره کنید، کافی است آن را هدایت (redirect) کنید:

borg create repo::archive myfiles 2>> logfile

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

سطح گزارش‌گیری در پیکربندی درونی به‌طور پیش‌فرض روی WARNING تنظیم شده است. دلیل آن این است که می‌خواهیم Borg بیشتر اوقات بی‌صدا بماند و تنها هشدارها، خطاها و پیام‌های بحرانی را نمایش دهد، مگر اینکه با دادن گزینه‌ای که مستلزم تولید خروجی است (مانند --list یا --progress) خروجی درخواست شده باشد.

سطوح گزارش‌گیری: DEBUG < INFO < WARNING < ERROR < CRITICAL

از گزینه --debug برای تنظیم سطح گزارش‌گیری روی DEBUG استفاده کنید - تا خروجی‌های سطوح اشکال‌زدایی (debug)، اطلاعاتی (info)، هشدار (warning)، خطا (error) و بحرانی (critical) را دریافت کنید.

از گزینه --info (یا -v یا --verbose) برای تنظیم سطح گزارش‌گیری روی INFO استفاده کنید - تا خروجی‌های سطوح اطلاعاتی، هشدار، خطا و بحرانی را دریافت کنید.

از گزینه --warning (پیش‌فرض) برای تنظیم سطح گزارش‌گیری روی WARNING استفاده کنید - تا خروجی‌های سطوح هشدار، خطا و بحرانی را دریافت کنید.

از گزینه --error برای تنظیم سطح گزارش‌گیری روی ERROR استفاده کنید - تا خروجی‌های سطوح خطا و بحرانی را دریافت کنید.

از گزینه --critical برای تنظیم سطح گزارش‌گیری روی CRITICAL استفاده کنید - تا خروجی‌های سطح بحرانی را دریافت کنید.

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

هشدار:

گزینه‌های --critical و --error جهت جامعیت ارائه شده‌اند و استفاده از آن‌ها توصیه نمی‌شود، چرا که ممکن است اطلاعات مهمی را از دست بدهید.

برنامه Borg می‌تواند با کدهای خروجی (rc) زیر به کار خود پایان دهد:

کد خروجی مفهوم
0 موفقیت‌آمیز (با سطح INFO ثبت می‌شود)
1 هشدار عمومی (عملیات به پایان عادی خود رسید، اما هشدارهایی وجود داشت -- باید گزارش را بررسی کنید؛ با سطح WARNING ثبت می‌شود)
2 خطای عمومی (مانند یک خطای مرگبار، یک استثنای محلی یا دوردست؛ عملیات به پایان عادی خود نرسید؛ با سطح ERROR ثبت می‌شود)
3..99 خطای مشخص (فعال‌شده با BORG_EXIT_CODES=modern)
100..127 هشدار مشخص (فعال‌شده با BORG_EXIT_CODES=modern)
128+N خاتمه‌یافته با سیگنال N (برای مثال 137 == kill -9)

اگر از گزینه --show-rc استفاده کنید، کد خروجی نیز در سطح مربوطه به عنوان آخرین ورودی گزارش ثبت می‌شود.

کدهای خروجی مدرن (کدهای بازگشتی، یا "rc") در این قسمت مستند شده‌اند: msgid

برنامه Borg از برخی متغیرهای محیطی برای خودکارسازی استفاده می‌کند:

عمومی (General):
در صورت تنظیم، از این مقدار برای مشخص کردن مکان پیش‌فرض مخزن استفاده می‌شود. اگر دستوری به یک آرگومان آرشیو نیاز داشته باشد، می‌توانید آن را به صورت ::archive خلاصه کنید. اگر دستوری به یک آرگومان مخزن نیاز داشته باشد، در صورتی که آرگومان موقعیتی الزامی باشد می‌توانید آن را حذف کرده یا به صورت :: خلاصه کنید.
در صورت تنظیم، از این مقدار برای پاسخ به پرسش عبارت عبور برای مخازن رمزگذاری‌شده استفاده می‌شود. این متغیر زمانی استفاده می‌شود که برای دسترسی به یک مخزن رمزگذاری‌شده به عبارت عبور نیاز باشد، و همچنین زمانی که در هنگام راه‌اندازی اولیه یک مخزن رمزگذاری‌شده، باید یک عبارت عبور جدید تنظیم شود. همچنین BORG_NEW_PASSPHRASE را ببینید.
در صورت تنظیم، از خروجی استاندارد دستور (خطوط جدید انتهایی حذف می‌شوند) برای پاسخ به پرسش عبارت عبور برای مخازن رمزگذاری‌شده استفاده می‌شود. این متغیر زمانی استفاده می‌شود که برای دسترسی به یک مخزن رمزگذاری‌شده به عبارت عبور نیاز باشد، و همچنین زمانی که در هنگام راه‌اندازی اولیه یک مخزن رمزگذاری‌شده، باید یک عبارت عبور جدید تنظیم شود. توجه داشته باشید که دستور بدون پوسته اجرا می‌شود؛ بنابراین متغیرهایی مانند $HOME کار خواهند کرد، اما ~ کار نخواهد کرد. اگر BORG_PASSPHRASE نیز تنظیم شده باشد، اولویت با آن خواهد بود. همچنین BORG_NEW_PASSPHRASE را ببینید.
در صورت تنظیم، یک توصیف‌گر فایل (file descriptor) را برای خواندن عبارت عبور مشخص می‌کند. برنامه‌هایی که borg را اجرا می‌کنند ممکن است یک لوله ناشناس (anonymous pipe) باز کنند و از آن برای ارسال عبارت عبور استفاده کنند. این روش از ارسال از طریق BORG_PASSPHRASE ایمن‌تر است، زیرا در برخی سیستم‌ها (مانند لینوکس) متغیرهای محیطی توسط سایر فرآیندها قابل بررسی هستند. اگر BORG_PASSPHRASE یا BORG_PASSCOMMAND نیز تنظیم شده باشند، آن‌ها اولویت خواهند داشت.
در صورت تنظیم، از این مقدار برای پاسخ به پرسش عبارت عبور هنگامی که یک عبارت عبور جدید درخواست می‌شود، استفاده خواهد شد. این متغیر در ابتدا بررسی می‌شود. اگر تنظیم نشده باشد، BORG_PASSPHRASE و BORG_PASSCOMMAND نیز بررسی خواهند شد. کاربرد اصلی این متغیر، خودکارسازی کامل دستور borg key change-passphrase است.
در صورت تنظیم، از این مقدار برای پاسخ به پرسش «نمایش عبارت عبور برای تأیید» (display the passphrase for verification) هنگام تعریف یک عبارت عبور جدید برای مخازن رمزگذاری‌شده استفاده می‌شود.
در صورت تنظیم روی «modern»، فرآیند borg کدهای خروج (rc) خاص‌تر و دقیق‌تری را بازمی‌گرداند. مقدار پیش‌فرض «legacy» است که کد ۲ را برای تمام خطاها، ۱ را برای تمام هشدارها و ۰ را برای موفقیت بازمی‌گرداند.
معمولاً Borg شناسه میزبان را از FQDN به اضافه نتیجه uuid.getnode() محاسبه می‌کند (که معمولاً یک شناسه یکتا بر اساس آدرس MAC رابط شبکه بازمی‌گرداند؛ مگر اینکه آن MAC کاملاً صفر باشد - در این صورت یک مقدار تصادفی بازمی‌گرداند که مطلوب ما نیست، زیرا حذف خودکار قفل‌های بی‌استفاده را مختل می‌کند). بنابراین اگر آدرس MAC کاملاً صفر دارید یا به دلایل دیگری می‌خواهید شناسه میزبان را از بیرون بهتر کنترل کنید، این متغیر محیطی را روی یک مقدار یکتا تنظیم کنید. اگر تمام FQDNهای شما یکتا هستند، می‌توانید صرفاً از FQDN استفاده کنید. در غیر این صورت، از <fqdn@uniqueid> استفاده کنید.
در صورت تنظیم، از این مقدار به عنوان نام میزبان استفاده می‌شود (به جای نامی که به طور خودکار شناسایی شده است)، مثلاً برای اجرای borg روی یک میزبان، اما معرفی خود به عنوان میزبانی دیگر (مشاهده شماره 9651#). این مورد بر نام میزبان ذخیره‌شده در آرشیوهای جدیداً ایجادشده و همچنین بر جانگهدارنده {hostname} تأثیر می‌گذارد.
در صورت تنظیم، از این مقدار به عنوان نام کاربری استفاده می‌شود (به جای نامی که به طور خودکار شناسایی شده است)، مثلاً برای اجرای borg با یک کاربر، اما معرفی خود به عنوان کاربری دیگر. این مورد بر نام کاربری ذخیره‌شده در آرشیوهای جدیداً ایجادشده و همچنین بر جانگهدارنده {user} تأثیر می‌گذارد.
در صورت تنظیم، از نام فایل ارائه‌شده به عنوان پیکربندی ثبت رویدادها با سبک INI https://docs.python.org/3/library/logging.config.html#configuration-file-format استفاده می‌شود. یک نمونه کانفیگ پایه‌ای را می‌توان در docs/misc/logging.conf یافت.
در صورت تنظیم، از این دستور به جای ssh استفاده می‌شود. می‌توان از این متغیر برای مشخص کردن گزینه‌های ssh، مانند یک فایل هویت سفارشی ssh -i /path/to/private/key استفاده کرد. برای مشاهده سایر گزینه‌ها، man ssh را ببینید. استفاده از گزینه خط فرمان --rsh CMD این متغیر محیطی را لغو می‌کند.
در صورت تنظیم، از مسیر ارائه‌شده به عنوان فایل اجرایی borg در سیستم راه دور استفاده می‌شود (در صورت تنظیم نشدن، پیش‌فرض «borg» است). استفاده از گزینه خط فرمان --remote-path PATH این متغیر محیطی را لغو می‌کند.
در صورت تنظیم روی مقداری با طول حداقل یک نویسه، به borg دستور می‌دهد از یک حافظه پنهان فایل جایگزین با نامی ویژه (بر اساس پسوند مشخص‌شده) استفاده کند. این متغیر می‌تواند برای جلوگیری از بارگذاری و ذخیره مدخل‌های کش برای منابع پشتیبان غیر از منابع فعلی استفاده شود.
در صورت تنظیم روی یک مقدار عددی، این متغیر حداکثر «زمان حیات» (time to live) را برای مدخل‌های کش فایل‌ها تعیین می‌کند (پیش‌فرض: 20). کش فایل‌ها برای تعیین سریع بدون تغییر بودن یک فایل استفاده می‌شود. بخش سؤالات متداول (FAQ) این مورد را با جزئیات بیشتر توضیح می‌دهد: always_chunking
در صورت تنظیم روی no (پیش‌فرض: yes)، از پوشه chunks.archive.d استفاده نخواهد شد. این کار مصرف فضای دیسک را کاهش می‌دهد اما سرعت همگام‌سازی مجدد حافظه پنهان را کُند می‌کند.
در صورت تنظیم روی no (پیش‌فرض: yes)، اطلاعات سیستم (مانند سیستم‌عامل، نسخه پایتون، ...) در استثناها نمایش داده نمی‌شود. لطفاً تنها در صورت داشتن دلایل موجه از آن استفاده کنید، زیرا تحلیل و ریشه‌یابی مشکلات را دشوارتر می‌کند.
کنترل می‌کند که آیا Borg نسخه msgpack را بررسی کند یا خیر. مقدار پیش‌فرض yes (بررسی دقیق) است. برای غیرفعال کردن بررسی نسخه و اجازه دادن به هر نسخه نصب‌شده از msgpack، آن را روی no تنظیم کنید. مسئولیت استفاده از این گزینه به عهده خودتان است؛ نسخه‌های ناسازگار یا معیوب msgpack ممکن است باعث ایجاد اشکالات نامحسوس یا خرابی داده‌های مخزن شوند.
پیاده‌سازی سطح پایین FUSE را که borg باید برای borg mount استفاده کند انتخاب می‌کند. این یک لیست از نام‌های پیاده‌سازی جداشده با کاما است که به ترتیب داده‌شده امتحان می‌شوند، به عنوان مثال:
  • pyfuse3,llfuse: پیش‌فرض، ابتدا تلاش برای بارگذاری pyfuse3، سپس تلاش برای بارگذاری llfuse.
  • llfuse,pyfuse3: ابتدا تلاش برای بارگذاری llfuse، سپس تلاش برای بارگذاری pyfuse3.
  • pyfuse3: فقط تلاش برای بارگذاری pyfuse3.
  • llfuse: فقط تلاش برای بارگذاری llfuse.
  • none: هیچ تلاشی برای بارگذاری پیاده‌سازی انجام نشود.
این متغیر می‌تواند برای تأثیرگذاری بر خودآزمایی‌های توکار (self-tests) borg استفاده شود. رفتار پیش‌فرض اجرای این آزمون‌ها در ابتدای هر بار فراخوانی دستور borg است.

می‌توان از BORG_SELFTEST=disabled برای غیرفعال کردن این آزمایش‌ها و در نتیجه صرفه‌جویی در زمان استفاده کرد. غیرفعال کردن آن برای کاربران عادی borg توصیه نمی‌شود، اما ارائه‌دهندگان فضای ذخیره‌سازی بزرگ borg می‌توانند پس از انجام حداقل یک آزمایش اولیه با borg (بدون غیرفعال کردن آزمون‌های خودکار) هنگام نصب یا ارتقای ماشین‌ها / سیستم‌عامل / borg، از این گزینه برای بهینه‌سازی سرورهای عملیاتی استفاده کنند.

فهرستی از رشته‌های جداشده با کاما که راهکارهای موقت (workarounds) را در borg فعال می‌کنند، برای مثال جهت دور زدن باگ‌های موجود در نرم‌افزارهای دیگر.

رشته‌های شناخته‌شده کنونی عبارتند از:

استفاده از کد ساده‌تر BaseSyncFile برای جلوگیری از مشکلات مربوط به sync_file_range. ممکن است برای اجرای borg روی WSL (زیرسیستم ویندوز برای لینوکس) یا در کانتینرهای systemd.nspawn روی برخی معماری‌ها (مانند ARM) به این گزینه نیاز داشته باشید. استفاده از این گزینه بر ایمنی داده‌ها تأثیر منفی نمی‌گذارد، اما ممکن است رفتار نوشتن روی دیسک به صورت ناگهانی‌تر و رگباری باشد (نه جریان پیوسته روی دیسک).
تلاش مجدد برای باز کردن یک فایل بدون پرچم O_NOATIME در صورتی که باز کردن فایل با O_NOATIME منجر به خطای EROFS شود. برای تهیه آرشیو از کپی‌های سایه‌ای حجم (volume shadow copies) در WSL1 (زیرسیستم ویندوز برای لینوکس ۱) به این گزینه نیاز خواهید داشت.
دور زدن عبارت عبور یا کلید گم‌شده برای یک مخزن در حالت authenticated (این مخازن فقط اعتبارسنجی می‌شوند، اما رمزگذاری نشده‌اند). اگر کلید در تنظیمات مخزن موجود نیست، key = anything را در آنجا اضافه کنید.

این راهکار موقت تنها برای شرایط اضطراری و تنها برای استخراج داده‌ها از یک مخزن آسیب‌دیده است (دسترسی فقط‌خواندنی):

BORG_WORKAROUNDS=authenticated_no_key borg extract repo::archive

پس از اینکه تمام داده‌های مورد نیاز خود را استخراج کردید، حتماً باید مخزن را حذف کنید:

BORG_WORKAROUNDS=authenticated_no_key borg delete repo

اکنون می‌توانید یک مخزن تازه راه‌اندازی (init) کنید. مطمئن شوید که دیگر از این راهکار موقت استفاده نمی‌کنید.

دور زدن TAMهای نامعتبر آرشیو که توسط نسخه‌های قبل از 1.2.5 borg ایجاد شده‌اند، شماره 7791# را ببینید.

این راهکار موقت احتمالاً فقط یک بار هنگام پیروی از دستورالعمل‌های ارتقا برای آسیب‌پذیری CVE-2023-36811 مورد نیاز است؛ archives_tam_vuln را ببینید.

در عملیات معمول محیط تولید، این راهکار هرگز نباید استفاده شود.

برخی از «پاسخ‌دهنده‌های خودکار» (در صورت تنظیم، به پرسش‌های تأیید به طور خودکار پاسخ می‌دهند):
برای «Warning: Attempting to access a previously unknown unencrypted repository»
برای «Warning: The repository at location ... was previously located at ...»
برای «This is a potentially dangerous function...» (دستور check --repair)
برای «You requested to completely DELETE the repository including all archives it contains:»

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

پوشه‌ها و فایل‌ها (Directories and files):
به طور پیش‌فرض $HOME یا ~$USER یا ~ است (به همین ترتیب). اگر می‌خواهید تمام پوشه‌های مخصوص borg را به طور یکجا به یک مسیر سفارشی منتقل کنید، تنها کاری که باید انجام دهید تغییر BORG_BASE_DIR است: سایر مسیرها برای حافظه پنهان، تنظیمات و غیره بر همین اساس تنظیم خواهند شد (با این فرض که آن‌ها را روی مقدار سفارشی متفاوتی تنظیم نکرده باشید).
به طور پیش‌فرض $BORG_BASE_DIR/.cache/borg است. اگر BORG_BASE_DIR به طور صریح تنظیم نشده باشد در حالی که متغیر محیطی XDG https://specifications.freedesktop.org/basedir-spec/0.6/ar01s03.html یعنی XDG_CACHE_HOME تنظیم شده باشد، در این صورت به جای آن از $XDG_CACHE_HOME/borg استفاده می‌شود. این پوشه شامل حافظه پنهان محلی است و برای کار با مخازن بزرگ ممکن است به فضای زیادی نیاز داشته باشد. مطمئن شوید که از جنبه‌های امنیتی مرتبط با مکان حافظه پنهان آگاه هستید: cache_security
به طور پیش‌فرض $BORG_BASE_DIR/.config/borg است. اگر BORG_BASE_DIR به طور صریح تنظیم نشده باشد در حالی که متغیر محیطی XDG https://specifications.freedesktop.org/basedir-spec/0.6/ar01s03.html یعنی XDG_CONFIG_HOME تنظیم شده باشد، در این صورت به جای آن از $XDG_CONFIG_HOME/borg استفاده می‌شود. این پوشه شامل تمام پوشه‌های پیکربندی borg است؛ برای توصیه امنیتی درباره داده‌های موجود در این پوشه، سؤالات متداول را ببینید: home_config_borg
به طور پیش‌فرض $BORG_CONFIG_DIR/security است. این پوشه شامل اطلاعاتی است که Borg برای ردیابی استفاده خود از NONCEها («عددهای فقط یک‌بار مصرف» - معمولاً در زمینه رمزنگاری) و سایر داده‌های مرتبط با امنیت استفاده می‌کند.
به طور پیش‌فرض $BORG_CONFIG_DIR/keys است. این پوشه شامل کلیدهای مخازن رمزگذاری‌شده است.
در صورت تنظیم، از مسیر داده‌شده به عنوان فایل کلید مخزن استفاده می‌شود. لطفاً توجه داشته باشید که این گزینه فقط برای برنامه‌های بسیار خاصی است که فایل‌های کلید را به طور کامل از بیرون مدیریت می‌کنند:
  • این تنظیم فقط برای حالت‌های keyfile اعمال می‌شود (نه برای حالت‌های repokey).
  • استفاده از یک مسیر کامل و مطلق به فایل کلید توصیه می‌شود.
  • تمام پوشه‌ها در مسیر داده‌شده باید وجود داشته باشند.
  • این تنظیم borg را مجبور می‌کند از فایل کلید در مکان مشخص‌شده استفاده کند.
  • فایل کلید باید وجود داشته باشد (برای بیشتر دستورات) یا ایجاد خواهد شد (borg init).
  • باید برای مخازن مختلف مسیرهای متفاوتی ارائه دهید.
  • باید به فایل کلید صحیح مطابق با مخزنی که دستور روی آن عمل خواهد کرد اشاره کنید.
این مکان جایی است که فایل‌های موقت ذخیره می‌شوند (ممکن است برای برخی عملیات‌ها به فضای موقت زیادی نیاز باشد)، برای جزئیات tempfile https://docs.python.org/3/library/tempfile.html#tempfile.gettempdir را ببینید.
ساخت و کامپایل (Building):
پوشه فایل هدر OpenSSL داده‌شده را به مکان‌های پیش‌فرض اضافه می‌کند (setup.py).
پیشوند پوشه داده‌شده را به مکان‌های پیش‌فرض اضافه می‌کند. اگر یک 'include/lz4.h' یافت شود، Borg به جای پیاده‌سازی همراه، با liblz4 سیستم پیوند داده می‌شود. (setup.py)
پیشوند پوشه داده‌شده را به مکان‌های پیش‌فرض اضافه می‌کند. اگر یک 'include/zstd.h' یافت شود، Borg به جای پیاده‌سازی همراه، با libzstd سیستم پیوند داده می‌شود. (setup.py)

لطفاً توجه داشته باشید:

  • هنگام استفاده از تأییدکننده‌های خودکار «yes»، بسیار مراقب باشید؛ هشدارهای دارای اعلان برای امنیت و ایمنی شما و داده‌هایتان وجود دارند.
  • همچنین هنگام قرار دادن عبارت عبور خود در یک اسکریپت بسیار مراقب باشید؛ مطمئن شوید که مجوزهای دسترسی فایل مناسبی دارد (مانند حالت 600، root:root).

ما اکیداً توصیه می‌کنیم از Borg (یا هر نرم‌افزار مشابه پایگاه داده دیگر) روی سیستم‌های فایل فاقد ژورنال مانند FAT استفاده نکنید، زیرا در صورت قطع برق (یا قطع ناگهانی درایو خارجی یا موارد خرابی مشابه) نمی‌توان هیچ‌گونه سازگاری داده‌ای را متصور شد.

اگرچه Borg از یک مخزن ذخیره داده استفاده می‌کند که در صورت استفاده در سیستم‌های فایل دارای ژورنال در برابر این خرابی‌ها مقاوم است، اما با برخی از سخت‌افزارها -- مستقل از نرم‌افزار مورد استفاده -- تضمین این امر امکان‌پذیر نیست. ما فهرستی از سخت‌افزارهای آسیب‌پذیر نمی‌شناسیم.

اگر مشکوک هستید که آیا مخزن Borg شما پس از رخ دادن یکی از خرابی‌های ذکرشده در بالا همچنان سازگار و خوانا است یا خیر، دستور borg check --verify-data را اجرا کنید تا از سازگاری آن اطمینان حاصل شود. نیازمندی‌های سیستم‌های فایل برای مخزن Borg:

  • نام‌های فایل طولانی
  • حداقل سه سطح دایرکتوری با نام‌های کوتاه
  • معمولاً اندازه فایل‌ها تا چند صد مگابایت. مخازن بزرگ ممکن است به فایل‌های بزرگ (بیشتر از ۲ گیگابایت) نیاز داشته باشند.
  • حداکثر ۱۰۰۰ فایل در هر پوشه.
  • فراخوانی‌های rename(2) / MoveFile(Ex) باید طبق مشخصات عمل کنند، یعنی در همان سیستم‌فایل باید یک عملیات جابه‌جایی باشد (نه کپی)، و در مورد یک پوشه اگر مقصد وجود داشته باشد و یک پوشه خالی نباشد باید ناموفق شود، زیرا این سازوکار برای قفل‌گذاری استفاده می‌شود.
  • پیوندهای سخت (Hardlinks) برای borg_upgrade مورد نیاز هستند (در صورتی که گزینه --inplace استفاده نشود). همچنین پیوندهای سخت برای به‌روزرسانی ایمن‌تر و مطمئن‌تر فایل‌ها (مانند فایل پیکربندی مخزن) استفاده می‌شوند، اما کد برنامه سعی می‌کند در صورت عدم پشتیبانی از پیوندهای سخت نیز کار کند.

برای نمایش مقادیر، Borg استانداردهای معمول مقیاس‌بندی را رعایت می‌کند. اندازه دیسک‌ها به صورت اعشاری (ده‌دهی) https://en.wikipedia.org/wiki/Decimal و با استفاده از توان‌های ۱۰ نمایش داده می‌شود (بنابراین kB به معنای ۱۰۰۰ بایت است). برای مصرف حافظه، از پیشوندهای دودویی https://en.wikipedia.org/wiki/Binary_prefix استفاده می‌شود و با استفاده از پیشوندهای دودویی IEC https://en.wikipedia.org/wiki/IEC_80000-13#Prefixes_for_binary_multiples و با توان‌های ۲ نشان داده می‌شوند (بنابراین KiB به معنای ۱۰۲۴ بایت است).

ما تاریخ و زمان را مطابق با استاندارد ISO-8601 قالب‌بندی می‌کنیم، یعنی: YYYY-MM-DD و HH:MM:SS (ساعت ۲۴ ساعته).

برای اطلاعات بیشتر درباره آن، ببینید: https://xkcd.com/1179

مگر اینکه خلاف آن ذکر شده باشد، تاریخ و زمان محلی را نمایش می‌دهیم. در داخل برنامه، تاریخ و زمان را به عنوان UTC ذخیره و پردازش می‌کنیم.

Borg ممکن است بسته به حجم مجموعه داده‌ای که با آن کار می‌کند، منابع زیادی مصرف کند.

اگر کسی از Borg به روش کلاینت/سرور (با مخزن :ssh) استفاده کند، مصرف منابع بخشی روی کلاینت و بخش دیگر روی سرور اتفاق می‌افتد.

اگر کسی از Borg به صورت یک تک‌فرآیند (با مخزن سیستم‌فایل محلی) استفاده کند، تمام مصرف منابع در همان یک فرآیند رخ می‌دهد؛ بنابراین کافی است منابع کلاینت + سرور را با هم جمع کنید تا مصرف تقریبی منابع به دست آید.

پردازنده (CPU) در سمت کلاینت:
  • borg create: قطعه‌بندی (chunking)، درهم‌سازی (hashing)، فشرده‌سازی، رمزنگاری را انجام می‌دهد (مصرف بالای پردازنده)
  • chunks cache sync: مصرف پردازنده نسبتاً سنگین، انجام تعداد زیادی عملیات جدول درهم‌سازی (hashtable).
  • borg extract: رمزگشایی، خروج از فشرده‌سازی (مصرف متوسط تا بالای پردازنده)
  • borg check: مشابه استخراج، اما به گزینه‌های ارائه‌شده بستگی دارد.
  • borg prune / borg delete archive: مصرف کم تا متوسط پردازنده
  • borg delete repo: روی سرور انجام می‌شود

از ۱۰۰٪ یک هسته فراتر نخواهد رفت زیرا کد در حال حاضر تک‌نخی (single-threaded) است. به ویژه سطوح فشرده‌سازی بالاتر zlib و lzma چرخه‌های قابل توجهی از پردازنده را مصرف می‌کنند. عملیات رمزنگاری ممکن است پردازنده کمی مصرف کند (در صورت شتاب‌دهی سخت‌افزاری) یا سنگین باشد (در صورت عدم شتاب‌دهی).

پردازنده (CPU) در سمت سرور:
معمولاً به پردازنده زیادی نیاز ندارد؛ صرفاً با پایگاه داده کلید/مقدار (مخزن) کار می‌کند و برای این کار از نمایه (index) مخزن بهره می‌برد.

دستور borg check: بررسی مخزن، جمع‌های کنترلی (checksums) تمام قطعه‌ها را محاسبه می‌کند (مصرف متوسط پردازنده)

دستور borg delete repo: مصرف کم پردازنده

پردازنده (فقط برای عملکرد کلاینت/سرور):
هنگام استفاده از borg به روش کلاینت/سرور با مخزن از نوع <ssh:-type>، فرآیندهای ssh مورد استفاده برای لایه انتقال به دلیل عملیات رمزنگاری که انجام می‌دهند - به ویژه اگر حجم زیادی از داده را جابه‌جا می‌کنید - به مقداری پردازنده در کلاینت و سرور نیاز خواهند داشت.
حافظه (RAM) در سمت کلاینت:
نمایه قطعه‌ها (chunks index) و نمایه فایل‌ها به دلایل کارایی در حافظه بارگذاری می‌شوند. ممکن است به مقادیر زیادی حافظه نیاز داشته باشد (پایین را ببینید). فشرده‌سازی، به خصوص فشرده‌سازی lzma با سطوح بالا ممکن است به مقادیر قابل توجهی حافظه نیاز داشته باشد.
حافظه (RAM) در سمت سرور:
فرآیند سرور نمایه مخزن را در حافظه بارگذاری می‌کند. ممکن است به مقادیر قابل توجهی حافظه نیاز داشته باشد، اما کمتر از سمت کلاینت (پایین را ببینید).
نمایه قطعه‌ها (فقط کلاینت):
متناسب با تعداد قطعه‌های داده در مخزن شماست. تعداد زیاد قطعه‌ها در مخزن شما به معنای یک نمایه قطعه‌های بزرگ است. امکان تنظیم دقیق پارامترهای قطعه‌بندی وجود دارد (گزینه‌های create را ببینید).
نمایه فایل‌ها (فقط کلاینت):
متناسب با تعداد فایل‌ها در آخرین پشتیبان‌گیری‌های شماست. می‌تواند خاموش شود (گزینه‌های create را ببینید)، اما در این صورت ممکن است پشتیبان‌گیری بعدی بسیار کندتر شود. مزیت سرعت حاصل از استفاده از حافظه پنهان فایل‌ها متناسب با اندازه فایل است.
نمایه مخزن (فقط سرور):
متناسب با تعداد قطعه‌های داده در مخزن شماست. تعداد زیاد قطعه‌ها در مخزن شما به معنای یک نمایه مخزن بزرگ است. امکان تنظیم دقیق پارامترهای قطعه‌بندی (گزینه‌های create را ببینید) برای تأثیرگذاری بر تعداد قطعه‌های ایجادشده وجود دارد.
فایل‌های موقت (کلاینت):
خواندن داده‌ها و فراداده‌ها از یک مخزن متصل‌شده با FUSE، تا اندازه تمام قطعه‌های کوچک و یکتاشده در مخزن فضا مصرف خواهد کرد. قطعه‌های بزرگ به صورت محلی در حافظه پنهان ذخیره نخواهند شد.
فایل‌های موقت (سرور):
حجم غیرقابل چشم‌پوشی از داده‌ها در پوشه موقت راه دور برای هر کلاینتی که به آن متصل می‌شود ذخیره خواهد شد. برای برخی سرورهای راه دور، این می‌تواند پوشه موقت پیش‌فرض در /tmp را پر کند. این مشکل را می‌توان با اطمینان از تنظیم صحیح متغیر محیطی $TMPDIR یا $TEMP یا $TMP برای فرآیند sshd رفع کرد. در برخی سیستم‌عامل‌ها، این کار را می‌توان فقط با تنظیم مقدار صحیح در bashrc. (یا فایل کانفیگ ورود معادل برای سایر پوسته‌ها) انجام داد؛ با این حال در سایر موارد ممکن است لازم باشد ابتدا PermitUserEnvironment yes را در فایل sshd_config فعال کنید، سپس environment="TMPDIR=/my/big/tmpdir" را در ابتدای کلید عمومی مورد استفاده در فایل authorized_hosts اضافه کنید.
فایل‌های حافظه پنهان (فقط کلاینت):
شامل نمایه قطعه‌ها و نمایه فایل‌ها است (به علاوه مجموعه‌ای از نمایه‌های قطعه‌های تک‌آرشیو که بسته به تعداد و اندازه آرشیو ممکن است به فضای دیسک زیادی نیاز داشته باشند - برای نحوه کاهش آن به سؤالات متداول مراجعه کنید).
شبکه (فقط برای عملکرد کلاینت/سرور):
اگر مخزن شما راه دور باشد، تمام داده‌های یکتاشده (و در صورت تمایل فشرده‌شده/رمزگذاری‌شده) طبیعتاً باید از طریق ارتباط منتقل شوند (نشانی اینترنتی مخزن ssh://). اگر از یک سیستم‌فایل شبکه‌ای متصل‌شده به صورت محلی استفاده می‌کنید، علاوه بر این، برخی عملیات‌های کپی که برای پشتیبانی از تراکنش‌ها استفاده می‌شوند نیز از طریق ارتباط انجام می‌شوند. اگر از چندین منبع در یک مخزن مقصد پشتیبان‌گیری کنید، ترافیک اضافی برای همگام‌سازی مجدد حافظه پنهان رخ خواهد داد.

علاوه بر ساختارهای معمولی فایل و پوشه، Borg می‌تواند موارد زیر را حفظ کند:

  • پیوندهای نمادین یا سیم‌لینک‌ها (به عنوان پیوند نمادین ذخیره می‌شود، پیوند دنبال نمی‌شود)
  • فایل‌های ویژه:
  • فایل‌های دستگاه نویسه‌ای و بلوکی (بازیابی از طریق mknod)
  • فایل‌های FIFO («لوله‌های نام‌گذاری‌شده» یا named pipes)
  • محتوای فایل‌های ویژه را می‌توان در حالت --read-special پشتیبان‌گیری کرد. به طور پیش‌فرض، فراداده برای ایجاد مجدد آن‌ها با mknod(2)، mkfifo(2) و غیره ذخیره می‌شود.
  • فایل‌های معمولی، دستگاه‌ها و FIFOهای دارای پیوند سخت (با در نظر گرفتن تمام موارد در همان آرشیو)
  • برچسب‌های زمانی با دقت نانوثانیه: mtime، atime، ctime
  • سایر برچسب‌های زمانی: birthtime (زمان ایجاد، در پلتفرم‌هایی که از آن پشتیبانی می‌کنند)
  • مجوزهای دسترسی:
  • شناسه‌های کاربر مالک و گروه مالک (UID / GID)
  • نام‌های کاربر مالک و گروه مالک (در صورتی که شناسه‌ها قابل حل باشند)
  • حالت/مجوزهای یونیکس (دسترسی‌های u/g/o، بیت‌های suid، sgid، sticky)

در برخی پلتفرم‌ها ویژگی‌های اضافی پشتیبانی می‌شوند:

Platform ACLs [5] xattr [6] Flags [7]
Linux Yes Yes Yes [1]
macOS Yes Yes Yes (all)
FreeBSD Yes Yes Yes (all)
OpenBSD n/a n/a Yes (all)
NetBSD n/a No [2] Yes (all)
Solaris and derivatives No [3] No [3] n/a
Windows (cygwin) No [4] No No

سایر سیستم‌عامل‌های شبه‌یونیکس نیز ممکن است کار کنند، اما به هیچ وجه آزمایش نشده‌اند.

توجه داشته باشید که بیشتر ویژگی‌های وابسته به پلتفرم به سیستم‌فایل نیز وابسته هستند. به عنوان مثال، ntfs-3g در لینوکس قادر به انتقال ACLهای NTFS نیست.

[1]
فقط «nodump»، «immutable»، «compressed» و «append» پشتیبانی می‌شوند. درخواست ویژگی 618# برای فلگ‌های بیشتر.
[2]
درخواست ویژگی 1332#
[3]
درخواست ویژگی 1337#
[4]
برنامه Cygwin تلاش می‌کند ACLهای NTFS را با درجات مختلفی از موفقیت به مجوزها نگاشت کند.
[5]
سازوکار بومی فهرست کنترل دسترسی (ACL) سیستم‌عامل. این مورد معمولاً دسترسی به ACLهای غیربومی را محدود می‌کند. برای مثال، ACLهای NTFS روی لینوکس با ntfs-3g به طور کامل در دسترس نیستند.
[6]
ویژگی‌های توسعه‌یافته (extended attributes)؛ جفت‌های کلید-مقدار متصل به یک فایل، که عمدتاً توسط سیستم‌عامل استفاده می‌شوند. این مورد شامل resource forkها در Mac OS X نیز می‌شود.
[7]
معروف به BSD flags. مجموعه پرچم‌های لینوکس [1] بین پلتفرم‌ها قابل حمل است. سیستم‌های BSD فلگ‌های اضافی تعریف می‌کنند.

borg-common(1) برای گزینه‌های رایج خط فرمان

borg-init(1), borg-create(1), borg-mount(1), borg-extract(1), borg-list(1), borg-info(1), borg-delete(1), borg-prune(1), borg-recreate(1)

borg-compression(1), borg-patterns(1), borg-placeholders(1)

The Borg Collective

orphan:

2026-07-18