BUPSTASH-PUT(1) User Commands BUPSTASH-PUT(1)

bupstash-put - ذخیره و پشتیبانگیری فایلها یا دادهها در مخزن bupstash

ذخیره داده‌ها در یک مخزن bupstash.

bupstash put [گزینه‌ها] [TAG=VAL...] [::] مسیرها...
bupstash put --exec [گزینه‌ها] [TAG=VAL...] [::] دستور

دستور bupstash put فایل‌ها، دایرکتوری‌ها یا خروجی دستورات را رمزگذاری کرده و در یک مخزن bupstash ذخیره می‌کند به‌گونه‌ای که فقط کلید رمزگشایی قادر به رمزگشایی آن باشد.

برای فایل‌های تکی، محتوا مستقیماً ذخیره می‌شود؛ برای چندین فایل، داده‌ها به شکلی ذخیره می‌شوند که بتوان آن‌ها را به‌صورت یک آرشیو tar بازیابی کرد، و برای دستورات، دستور اجرا شده و خروجی استاندارد (stdout) آن به مخزن ارسال می‌شود.

داده‌های ذخیره‌شده در یک مخزن bupstash به‌طور خودکار یکتاسازی (deduplicate) می‌شوند، به‌طوری که اسنپ‌شات‌های یکسان یا مشابه حداقل فضای اضافی دیسک را اشغال کنند. برای عملکرد افزایشی بهینه، از گزینه --send-log که در بخش نکات استفاده شرح داده شده است استفاده کنید.

تمام عملیات‌های put می‌توانند به مجموعه‌ای از برچسب‌های متاداده رمزگذاری‌شده اختیاری مرتبط شوند که با استفاده از bupstash-list(1) قابل جستجو هستند. برچسب‌ها در خط فرمان با قالب ساده KEY=VALUE مشخص می‌شوند. کلیدهای معتبر برچسب باید با عبارت باقاعده ^([a-zA-Z0-9\\-_]+)=(.+)$ مطابقت داشته باشند، یعنی کلیدهای برچسب باید نویسه‌های الفبایی-عددی بوده و می‌توانند شامل - و _ باشند. پردازش برچسب‌ها با رسیدن به نخستین آرگومانی که با این الگو مطابقت نداشته باشد متوقف می‌شود.

آرگومان نشانگر ویژه :: می‌تواند برای اجبار به پایان تجزیه برچسب‌ها استفاده شود، اما معمولاً ضروری نیست.

توجه داشته باشید که بارگذاری‌های همزمان چندگانه در یک مخزن یکسان ایمن بوده و پشتیبانی می‌شوند، مشروط بر اینکه تمام کلاینت‌ها از طریق یک سرور به مخزن دسترسی داشته باشند و بنابراین قفل‌های فایل مخزن را رعایت کنند. برخی از سیستم‌های فایل شبکه‌ای (مانند NFS و sshfs) همیشه قفل‌های فایل راه دور را رعایت نمی‌کنند و بنابراین پشتیبانی نمی‌شوند. همواره ترجیح داده می‌شود که از طریق یک نشانی اینترنتی با سبک ssh:// یا یک نمونه از bupstash serve به یک مخزن راه دور متصل شوید.

هنگام ارسال داده‌ها، bupstash متاداده مربوط به آنچه در عملیات 'put' قبلی ارسال شده را در فایلی موسوم به سند لاگ ارسال (send log) ثبت می‌کند.

لاگ ارسال دو هدف اصلی را دنبال می‌کند:

  • شناسه‌های قطعات داده‌ای را که در آخرین 'put' به مخزن ارسال شده‌اند به خاطر می‌سپارد، و به bupstash اجازه می‌دهد از ارسال مجدد آن قطعات روی شبکه به‌طور مکرر جلوگیری کند.
  • نگاشتی از مسیرهای فایل به داده‌هایی که قبلاً ارسال شده‌اند را ذخیره می‌کند، و به bupstash اجازه می‌دهد هنگام ایجاد اسنپ‌شات مکرر از یک دایرکتوری یکسان، از پردازش فایل‌ها صرف‌نظر کند.

لاگ ارسال تنها داده‌هایی را که قبلاً ارسال شده‌اند به خاطر می‌سپارد؛ بنابراین برای استفاده بهینه از 'put'، به هر وظیفه پشتیبان‌گیری یک فایل لاگ ارسال اختصاصی بدهید. به عنوان مثال، اگر اسکریپت پشتیبان‌گیری دارید که یک دایرکتوری را به عنوان یک کار cron ذخیره می‌کند، بهتر است به آن اسکریپت فایل لاگ ارسال مختص خود را بدهید تا تمام اجراهای بعدی با داده‌های ورودی مشابه، از همان لاگ ارسال مشترک استفاده کنند.

مثال:

$ bupstash put --send-log /root/bupstash-backups.sendlog /home/
# پشتیبان‌گیری دوم افزایشی و سریع است زیرا از send log استفاده می‌کند.
$ bupstash put --send-log /root/bupstash-backups.sendlog /home/

ابزار Bupstash از بارگذاری سیستم‌فایلی که همزمان در حال تغییر است پشتیبانی می‌کند، اما با این هشدار که bupstash نمی‌تواند تضمین کند که سیستم‌فایل در یک وضعیت یکپارچه قرار دارد. اگر bupstash در حال خواندن یک فایل یا دایرکتوری باشد در حالی که همزمان توسط یک برنامه در حال تغییر است، ممکن است اسنپ‌شات bupstash حاوی داده‌هایی از چند نقطه زمانی مختلف باشد و ترکیب آن‌ها بالقوه نامعتبر یا خراب باشد.

تنها راه مطمئن برای تضمین یکپارچگی داده‌ها، استفاده از یک سیستم‌فایل با قابلیت ایجاد اسنپ‌شات است. با استفاده از اسنپ‌شات‌های سیستم‌فایل می‌توانید یک نمای یکپارچه از سیستم‌فایل ایجاد کنید و سپس پشتیبان‌گیری bupstash را روی آن اسنپ‌شات انجام دهید. در لینوکس برخی گزینه‌ها برای ایجاد اسنپ‌شات‌های یکپارچه شامل اسنپ‌شات‌های ZFS، BTRFS و همچنین LVM هستند.

گزینه دیگر، انجام عملیات put در زمانی است که احتمال کمتری وجود دارد فایل‌ها تغییر کنند؛ این کار بدون پیچیدگی‌های اضافی برای بسیاری از افراد پشتیبان‌های به اندازه کافی مناسبی فراهم می‌کند.

ابزار bupstash به‌طور خودکار برچسب‌های پیش‌فرضی را تنظیم می‌کند.

در حال حاضر این برچسب‌ها عبارتند از:

•
name، که روی FILENAME یا DIRNAME.tar تنظیم می‌شود؛ هنگام ذخیره در حالت --exec حذف می‌شود.

برچسب‌های پیش‌فرض را می‌توان با مشخص کردن دستی آن‌ها بازنویسی کرد.

برچسب‌های زیر رزرو شده‌اند و نمی‌توان آن‌ها را به‌صورت دستی تنظیم کرد:

  • id
  • decryption-key-id
  • size
  • timestamp

در صورت تنظیم گزینه --print-file-actions، دستور bupstash put برای هر ورودی دایرکتوری که پردازش می‌شود یک خط در stderr چاپ می‌کند.

هر خط خروجی ساختاری به شکل زیر دارد:

$action $type $PATH

با اقدامات ممکن:

  • + فایلی به اسنپ‌شات افزوده شد.
  • ~ تطابق با حافظه نهان stat امکان صرف‌نظر از ارسال فایل را فراهم کرد.
  • x مسیری بر اساس قاعده استثنا از اسنپ‌شات کنار گذاشته شد.

با انواع ممکن:

  • f فایل
  • l پیوند نمادین
  • c دستگاه کاراکتری
  • b دستگاه بلوکی
  • d دایرکتوری
  • p لوله نام‌گذاری‌شده (fifo)

  • دستور bupstash put داده‌ها را به‌طور خودکار یکتاسازی و فشرده می‌کند، بنابراین اگر می‌خواهید یکتاسازی و فشرده‌سازی بهینه‌ای داشته باشید، از ارسال داده‌های فشرده‌شده یا رمزگذاری‌شده خودداری کنید.
  • دستور bupstash serve --allow-put را با دستورات اجباری ssh ترکیب کنید تا کلیدهای ssh محدودی بسازید که فقط بتوانند پشتیبان‌های جدید بیفزایند اما نتوانند پشتیبان‌های قدیمی را فهرست یا حذف کنند.
  • تفاوت میان هدایت خروجی دستور tar به bupstash put و استفاده مستقیم از bupstash put روی یک دایرکتوری در این است که در حالت دوم می‌توان از send log استفاده کرد و از خواندن فایل‌هایی که قبلاً به سرور ارسال شده‌اند اجتناب نمود، و همچنین می‌توان یک فهرست‌بندی اسنپ‌شات برای دستورات دیگری مانند bupstash-list-contents(1) ایجاد کرد.

مخزنی که باید به آن متصل شد. در صورت پیکربندی دسترسی ssh، برای مخازن راه دور می‌تواند به شکل ssh://$SERVER/$PATH باشد. در صورت عدم تعیین، از BUPSTASH_REPOSITORY استفاده می‌شود.
کلید مورد استفاده برای رمزگذاری داده‌ها و متاداده‌ها. در صورت عدم تنظیم، به BUPSTASH_KEY پیش‌فرض می‌شود.
آرگومان COMMAND دستوری برای اجرا است، که در آن stdout به عنوان یک ورودی در مخزن bupstash ذخیره می‌شود. تنها در صورتی ورودی ایجاد می‌شود که دستور با یک کد وضعیت موفق پایان یابد.
افزودن یک الگوی تطبیق (glob) برای فیلتر کردن و استثنا کردن ورودی‌ها از آرشیو tar نهایی. این گزینه می‌تواند چندین بار مشخص شود، و در صورتی که اسنپ‌شات دایرکتوری بارگذاری نشود نادیده گرفته می‌شود. الگو با مسیرهای مطلق تطبیق داده می‌شود و نباید به / ختم شود. الگوهای بدون / یا **/ در ابتدا به عنوان تطبیق نام فایل تلقی می‌شوند، یعنی به‌طور خودکار **/ به ابتدای آن‌ها اضافه می‌شود. قوانین معمول الگو اعمال می‌شوند: * با همه چیز در یک سطح مطابقت دارد، ** با هر تعداد سطح مطابقت دارد، ? با یک نویسه منفرد مطابقت دارد، و […] با یک نویسه منفرد از مجموعه داده‌شده مطابقت دارد (و همچنین می‌تواند برای فرار دادن نویسه‌های خاص دیگر استفاده شود: [?]).
استثنا کردن محتویات یک دایرکتوری اگر حاوی فایلی با نام مشخص‌شده باشد. می‌تواند چندین بار مشخص شود. این کار همچنان از خود دایرکتوری حاوی فایل نشانگر پشتیبان می‌گیرد. نام‌های معمول فایل‌های نشانگر عبارتند از CACHEDIR.TAG، .backupexclude یا .no-backup.
مسیر فایل لاگ ارسال؛ در صورت تنظیم متغیرهای محیطی مربوطه، به‌ترتیب اولویت یکی از موارد $BUPSTASH_SEND_LOG، $XDG_CACHE_HOME/.cache/bupstash/bupstash.sendlog یا $HOME/.cache/bupstash/bupstash.sendlog خواهد بود.
غیرفعال کردن استفاده از لاگ ارسال؛ تمام داده‌ها مجدداً روی شبکه نوشته خواهند شد. متضمن --no-stat-caching است.
عدم استفاده از حافظه نهان stat برای پرهیز از ارسال فایل‌ها به مخزن.
عدم تنظیم برچسب‌های پیش‌فرض.
الگوریتم فشرده‌سازی، یکی از 'none'، 'lz4' یا 'zstd[:$level]'. پیش‌فرض 'zstd:3' است.
نادیده گرفتن خطاهای عدم دسترسی (permission denied)، و صرف‌نظر از آن فایل‌ها یا دایرکتوری‌ها.
نقاط اتصال دیگر (mount points) در سیستم‌فایل را پیمایش نمی‌کند.
ذخیره ویژگی‌های گسترده (xattrs) ورودی‌های دایرکتوری؛ تنها هنگام ذخیره یک دایرکتوری استفاده می‌شود.
چاپ اقدامات فایل در قالب '$a $t $path' در stderr هنگام پردازش دایرکتوری‌ها؛ برای جزئیات بخش 'اقدامات روی فایل' را ببینید.
چاپ آمار put در stderr پس از اتمام کار.
تعداد رشته‌های پردازنده (threads) برای خواندن خط‌لوله‌ای و موازی متاداده فایل‌ها. مقدار پیش‌فرض 1 است.
تعداد رشته‌های پردازنده برای خواندن، هش کردن، فشرده‌سازی و رمزگذاری خط‌لوله‌ای و موازی. مقدار پیش‌فرض برابر با تعداد پردازنده‌ها است.
غیرفعال کردن نشانگرهای پیشرفت (در صورتی که stderr یک ترمینال تعاملی نباشد نیز نشانگرهای پیشرفت غیرفعال می‌شوند).
حالت بی‌صدا؛ متضمن --no-progress است.
حالت پرحرف (verbose)؛ متضمن --print-file-actions و --print-stats است.

مخزنی که باید به آن متصل شد. در صورت پیکربندی دسترسی ssh برای مخازن راه دور، می‌تواند به شکل ssh://$SERVER/$PATH باشد.
دستوری که برای اتصال به یک نمونه از bupstash-serve(1) اجرا می‌شود. این امکان اتصالات پیچیده‌تر به مخزن را برای کاربردهای خاص‌تر فراهم می‌کند.
مسیر کلیدی که برای رمزگذاری داده‌ها استفاده خواهد شد. پس از ارسال داده‌ها، تنها کلید اصلی مرتبط قادر به رمزگشایی آن‌ها خواهد بود.
دستوری برای اجرا که باید داده‌های کلید را چاپ کند؛ می‌تواند به‌جای BUPSTASH_KEY برای واکشی کلید از مکان‌های دلخواه مانند شبکه یا سایر فضاهای ذخیره‌سازی امن استفاده شود.
مسیر فایل لاگ ارسال، که توسط --send-log لغو و جایگزین می‌شود. برای توضیحات در مورد نحوه استفاده از لاگ ارسال جهت بارگذاری‌های افزایشی کارآمد، بخش 'ارسال افزایشی' را ببینید.
هنگامی که لاگ ارسال فعال باشد، bupstash تقریباً هر BUPSTASH_CHECKPOINT_SECONDS ثانیه یک‌بار نقطه بازرسی (checkpoint) ایجاد می‌کند. اگر یک بارگذاری پس از یک نقطه بازرسی موفق قطع شود، نیازی به ارسال مجدد داده‌ها روی شبکه نخواهد بود. مقدار پیش‌فرض این گزینه 600 است که برابر با 10 دقیقه می‌باشد.

قابلیت داخلی ذخیره دایرکتوری، یک آرشیو tar از یک دایرکتوری ایجاد می‌کند و همزمان فایل‌های تکراری را یکتاسازی (deduplicate) می‌نماید.

# تهیه اسنپ‌شات از یک دایرکتوری.
$ ID="$(bupstash put ./data)"
# فهرست کردن محتویات اسنپ‌شات.
$ bupstash list-contents id="$ID"
# دریافت اسنپ‌شات.
$ bupstash get id="$ID" | tar -xf -

export BUPSTASH_KEY="/backups/backups-secret.key"
export BUPSTASH_REPOSITORY="ssh://$SERVER/home/me/bupstash-repository"
$ bupstash put ./data.file
$ bupstash put ./directory
$ bupstash put ./multiple-files.txt ./directory

# تهیه اسنپ‌شات از یک پایگاه‌داده postgres با pgdump
$ bupstash put --exec name=dbdump.sql pgdump mydb

$ export BUPSTASH_REPOSITORY_COMMAND="ssh -F ./my-ssh-config me@$SERVER bupstash serve /my/repo"
$ bupstash put ./files

bupstash(1), bupstash-keyfiles(7)

2026-09-01 bupstash