نام (NAME)

bupstash-list - جستجو و فهرستکردن اسنپشاتهای موجود در مخزن

خلاصه دستور (SYNOPSIS)

فهرست کردن آیتم‌ها در یک مخزن bupstash.

bupstash list [گزینه‌ها] پرس‌وجو...

توضیحات (DESCRIPTION)

دستور bupstash list متاداده‌های آیتم‌های ذخیره‌شده در مخزن bupstash را واکشی، رمزگشایی و چاپ می‌کند. این دستور می‌تواند برای جستجو در پایگاه‌داده با زبان پرس‌وجوی bupstash استفاده شود.

برای فهرست‌کردن آیتم‌ها، تنها رمزگشایی متاداده‌ها لازم است؛ بنابراین یک کلید متاداده حتی بدون دسترسی به کلید رمزگشایی داده‌ها برای پرس‌وجوی آیتم‌ها کافی خواهد بود.

زبان پرس‌وجو (QUERY LANGUAGE)

برای مستندات کامل درباره زبان پرس‌وجو، به bupstash-query-language(7) مراجعه کنید.

مثال‌های پرس‌وجوی فهرست:

$ bupstash list name='*.tar'
...
$ bupstash list timestamp='2020*'
...

برچسب‌های ویژه (SPECIAL TAGS)

ابزار Bupstash به طور خودکار برچسب‌های ویژه‌ای را درج می‌کند که می‌توان آن‌ها را مشاهده کرد و روی آن‌ها پرس‌وجو انجام داد؛ این برچسب‌ها در زیر تشریح شده‌اند.

این برچسب ویژه هنگامی درج می‌شود که گزینه --query-encrypted استفاده شده باشد؛ این ویژگی امکان جستجو بر اساس شناسه کلیدی را فراهم می‌سازد که برای رمزگشایی آیتم داده‌شده استفاده خواهد شد. این برچسب بیش از همه برای هرس کردن و حذف پشتیبان‌هایی کاربرد دارد که کلید رمزگشایی آن‌ها را در اختیار ندارید.

size

این برچسب اندازه جریان داده و هرگونه متاداده نمایه‌ای مرتبط با اسنپ‌شات را نشان می‌دهد. این بدان معناست که در مورد اسنپ‌شات‌ها، اندازه ممکن است دقیقاً با اندازه جریان داده بازیابی‌شده توسط bupstash-get(1) مطابقت نداشته باشد.

timestamp

زمان ایجاد آیتم با قالب YYYY/MM/DD HH:MM:SS.

حافظه موقت پرس‌وجو (QUERY CACHING)

از آنجا که تمام داده‌ها به صورت رمزگذاری‌شده در کارساز (سرور) ذخیره می‌شوند، متاداده‌های آیتم‌ها ابتدا باید با ماشین محلی همگام‌سازی شوند و سپس جهت اجرای یک پرس‌وجو، در سمت کلاینت رمزگشایی گردند. به فایلی که حاوی متاداده‌های همگام‌شده و رمزگذاری‌شده است، حافظه موقت پرس‌وجو (query cache) گفته می‌شود.

مسیر فایل حافظه موقت پرس‌وجو (query-cache)، در صورت تنظیم بودن متغیرهای محیطی مربوطه، به ترتیب اولویت پیش‌فرض یکی از مقادیر زیر است: $BUPSTASH_QUERY_CACHE یا $XDG_CACHE_HOME/.cache/bupstash/bupstash.qcache یا $HOME/.cache/bupstash/bupstash.qcache.

به عنوان یک حالت خاص، پرس‌وجویی که تنها از یک شناسه کاملاً مشخص تشکیل شده باشد (مانند id=$FULL_ID) نیازی به استفاده از حافظه موقت پرس‌وجو نخواهد داشت و در عوض پرس‌وجو می‌تواند مستقیماً به کارساز ارسال شود. این بدان معناست که هنگام اجرای هر دستوری که انتظار یک پرس‌وجو را دارد، مشخص‌کردن کامل یک شناسه همیشه کارآمدتر خواهد بود.

قالب‌های خروجی (OUTPUT FORMATS)

Human

هنگامی که --format روی human تنظیم شده باشد، bupstash list سطرهایی شامل موارد زیر خروجی می‌دهد:

KEY=VALUE KEY=VALUE KEY=VALUE ....

که در آن هر کلید و مقدار متناظر با برچسبی است که می‌توان روی آن جستجو انجام داد.

JSONl1

هنگامی که --format روی jsonl1 تنظیم شده باشد، bupstash list در هر سطر یک شیء JSON خروجی می‌دهد.

هر سطر دارای طرح‌واره (schema) جیسون زیر است:

{
  "id": hexstring,
  "decryption_key_id": hexstring,
  "data_tree": {
    "address": hexstring,
    "height": number,
    "data_chunk_count": number
  },
  "index_tree": {
    "address": hexstring,
    "height": number,
    "data_chunk_count": number
  },
  "data_size": number, // If decryption key present.
  "index_size": number,  // If decryption key present.
  "put_key_id": hexstring,  // If decryption key present.
  "data_hash_key_part": hexstring,  // If decryption key present.
  "index_hash_key_part": hexstring,  // If decryption key present.
  "unix_timestamp_millis": number,
  "tags": {
    string : string,
    ...
}

اگر --query-encrypted مشخص شده باشد، برچسب‌ها و متاداده‌های رمزگذاری‌شده حذف می‌شوند.

گزینه‌ها (OPTIONS)

-r, --repository REPO: مخزنی که باید به آن متصل شد؛ در صورت پیکربندی دسترسی ssh برای مخازن دوردست، می‌تواند به شکل ssh://$SERVER/$PATH باشد. در صورت عدم تعیین، از مقدار متغیر BUPSTASH_REPOSITORY استفاده می‌شود.
-k, --key KEY: کلید اصلی مورد استفاده برای رمزگشایی داده‌ها و متاداده‌ها. در صورت تنظیم نشدن، مقدار پیش‌فرض آن BUPSTASH_KEY است.
--query-encrypted: پرس‌وجو هیچ متاداده‌ای را رمزگشایی نمی‌کند و به شما امکان می‌دهد آیتم‌هایی را فهرست کنید که کلید رمزگشایی آن‌ها را در اختیار ندارید. این گزینه برچسب پرس‌وجوی ساختگی 'decryption-key-id' را درج می‌کند.
--query-cache PATH: مسیر فایل حافظه موقت پرس‌وجو (query-cache)؛ در صورت تنظیم بودن متغیرهای محیطی مربوطه، به ترتیب اولویت پیش‌فرض یکی از مقادیر زیر است: $BUPSTASH_QUERY_CACHE یا $XDG_CACHE_HOME/.cache/bupstash/bupstash.qcache یا $HOME/.cache/bupstash/bupstash.qcache.
--format FORMAT: تنظیم قالب خروجی به یکی از موارد 'human' یا 'jsonl'.
--utc-timestamps: نمایش و جستجو بر اساس برچسب‌های زمانی به وقت جهانی (UTC) به جای زمان محلی.
--no-progress: غیرفعال‌سازی نشانگرهای پیشرفت (اگر stderr یک ترمینال تعاملی نباشد نیز نشانگرهای پیشرفت غیرفعال می‌شوند).
-q, --quiet: اجرای بی‌صدا؛ متضمن --no-progress است.

محیط (ENVIRONMENT)

BUPSTASH_REPOSITORY: مخزنی که باید به آن متصل شد. در صورت پیکربندی دسترسی ssh می‌تواند برای مخازن دوردست به شکل ssh://$SERVER/$PATH باشد.
BUPSTASH_REPOSITORY_COMMAND: دستوری برای اجرا جهت اتصال به یک نمونه از bupstash-serve(1). این متغیر اتصالات پیچیده‌تری را به مخزن برای کاربردهای خاص فراهم می‌کند.
BUPSTASH_KEY: مسیر کلید اصلی که برای رمزگشایی داده‌ها و متاداده‌ها استفاده خواهد شد.
BUPSTASH_KEY_COMMAND: دستوری برای اجرا که باید داده‌های کلید را در خروجی چاپ کند؛ می‌تواند به جای BUPSTASH_KEY برای واکشی کلید از مکان‌های دلخواه مانند شبکه یا سایر فضاهای ذخیره‌سازی محرمانه به کار رود.
BUPSTASH_QUERY_CACHE: مسیر فایل حافظه موقت پرس‌وجو (query cache) جهت استفاده.

مثال‌ها (EXAMPLES)

فهرست کردن آیتم‌های منطبق با یک پرس‌وجو

$ bupstash list name=backup.tar and timestamp=2020/07/*
id="aa87fdbc72241f363568bbb888c0834e" name="backup.tar" size="106.34MB" timestamp="2020-07-24 15:25:00"
id="d271ec0b989cfc20e10d01380115747e" name="backup.tar" size="146.38MB" timestamp="2020-07-29 15:25:24"
...

همچنین ببینید (SEE ALSO)

bupstash(1), bupstash-list-contents(1), bupstash-keyfiles(7), bupstash-query-language(7)