'\"! tbl | nroff \-man
'\" t macro stdmacro

.de SAMPLE
.br
.RS 0
.nf
.nh
..
.de ESAMPLE
.hy
.fi
.RE
..
.TH DEBUGINFOD 8
.SH "نام (NAME)"
debuginfod \- دیمن سرور فایل مبتنی بر HTTP مرتبط با اطلاعات اشکال‌زدایی (debuginfo)

.SH "خلاصه دستور (SYNOPSIS)"
.B debuginfod
[\fIگزینه‌ها\fP]... [\fIمسیر\fP]...

.SH "توضیحات (DESCRIPTION)"
دستور
\fBdebuginfod\fP
آرتیفکت‌ها و پرونده‌های مرتبط با اطلاعات اشکال‌زدایی (debuginfo) را از طریق پروتکل HTTP ارائه می‌دهد. این دیمن به‌صورت دوره‌ای مجموعه‌ای از دایرکتوری‌ها را برای یافتن فایل‌های ELF/DWARF و کدهای منبع مرتبط با آن‌ها، و همچنین فایل‌های آرشیو حاوی موارد مذکور، پویش می‌کند تا نمایه‌ای بر اساس شناسه ساخت (buildid) آن‌ها ایجاد نماید. این نمایه زمانی استفاده می‌شود که کلاینت‌های راه دور از طریق وب‌سرویس (HTTP webapi)، برای دریافت این فایل‌ها بر اساس همان buildid اقدام می‌کنند.
.PP
چنانچه یک debuginfod نتواند درخواستی برای آرتیفکت یک buildid خاص را شخصاً پاسخ دهد، و برای ارتباط با سرورهای debuginfod بالادستی (upstream) پیکربندی شده باشد، همانند
\fBdebuginfod\-find\fP
همان اطلاعات را از آن‌ها استعلام می‌کند. در صورت موفقیت، محتوای فایل را به‌صورت محلی در حافظه پنهان (cache) ذخیره کرده و سپس آن را به درخواست‌کننده اصلی بازپخش (relay) می‌کند.
.PP
نمایه‌سازی PATHهای ارائه‌شده با استفاده از چندین رشته (thread) انجام می‌پذیرد. یک رشته به‌صورت دوره‌ای تمام PATHهای ارائه‌شده را به‌صورت منطقی یا فیزیکی پیمایش می‌کند (گزینه
\fB\-L\fP
را ببینید). مسیرهای تکراری نادیده گرفته می‌شوند. می‌توانید از نام یک فایل به عنوان PATH استفاده کنید، اما در این حالت ممکن است نمایه‌سازی کد منبع ناقص بماند؛ ترجیحاً از دایرکتوری حاوی فایل‌های باینری استفاده نمایید. رشته پیمایشگر، تمامی فایل‌های منطبق (گزینه‌های
\fB\-I\fP
و
\fB\-X\fP
را ببینید) را درون یک صف کاری قرار می‌دهد. مجموعه‌ای از رشته‌های پویشگر (گزینه
\fB\-c\fP
را ببینید) در صف کاری منتظر می‌مانند تا فایل‌ها را به صورت موازی تحلیل کنند.
.PP
اگر گزینه
\fB\-F\fP
داده شود، هر فایل به عنوان یک فایل ELF/DWARF پویش می‌شود. فایل‌های منبع بر اساس مشخصه‌های AT_comp_dir (دایرکتوری کامپایل) درون فایل‌های DWARF، با آن‌ها تطبیق داده می‌شوند. هشدار: فایل‌های منبع فهرست‌شده در DWARF ممکن است مسیری در
\fIهر کجای\fP
سیستم فایل باشند، و debuginfod در صورت تقاضا بی‌درنگ محتوای آن‌ها را ارائه خواهد داد. (تصور کنید یک فایل دستکاری‌شده DWARF مسیر
\fI/etc/passwd\fP
را به عنوان فایل منبع قید کرده باشد.) اگر این موضوع مایه نگرانی است، فایل‌های باینری خود را بازرسی کنید:

.SAMPLE
% eu-srcfiles -e BINARY
.ESAMPLE
.PP
اگر هر یک از گزینه‌های
\fB\-R\fP،
\fB\-U\fP
یا
\fB\-Z\fP
ارائه شوند، هر فایل به عنوان یک فایل آرشیو که ممکن است حاوی فایل‌های ELF/DWARF/منبع باشد، پویش می‌شود. فایل‌های آرشیو بر اساس پسوندشان شناسایی می‌شوند. اگر
.B \-R
ارائه شود، فایل‌های ".rpm" پویش می‌شوند؛ اگر
.B \-U
ارائه شود، فایل‌های ".deb" و ".ddeb" پویش می‌شوند؛ و اگر
.B \-Z
ارائه شود، پسوندهای فهرست‌شده پویش خواهند شد.
.PP
به دلیل پیچیدگی‌هایی نظیر اطلاعات اشکال‌زدایی فشرده‌شده با DWZ، ممکن است شناسایی تمام کدهای منبع به
\fIدو\fP
دور پیمایش نیاز داشته باشد. فایل‌های منبع مربوط به فایل‌های باینری درون آرشیوها، تنها از داخل همان آرشیوها ارائه می‌شوند، بنابراین هشدار ذکرشده برای
.B \-F
در اینجا اعمال نمی‌گردد. اگر یک فایل منبع یکسان در چندین آرشیو مختلف پیدا شود، یک روش اکتشافی نزدیک‌ترین آرشیو به آرشیو حاوی debuginfo را انتخاب می‌کند ("نزدیک‌ترین" به معنای "طولانی‌ترین پیشوند مشترک در نام آرشیوها" است). توجه داشته باشید که به دلیل سیاست‌ها و سازوکارهای بسته‌بندی دبیان/اوبونتو، debuginfod به هیچ وجه نمی‌تواند فایل‌های منبع را برای بسته‌های DEB/DDEB حل کند. در این موارد استفاده از گزینه
\fB\-\-disable\-source\-scan\fP
را در نظر داشته باشید.
.PP
اگر هیچ PATHای مشخص نشود، یا هیچ‌یک از گزینه‌های پویش ارائه نگردد، در این صورت
\fBdebuginfod\fP
صرفاً محتوایی را ارائه می‌دهد که در تمام اجراهای قبلی در نمایه خود گردآوری کرده است، پایگاه‌داده را به‌صورت دوره‌ای پیراسته‌سازی (groom) می‌کند، و با هر سرور debuginfod بالادستی همکاری و فدراسیون تشکیل می‌دهد. در حالت
\fIغیرفعال (passive)\fP،
دیمن
\fBdebuginfod\fP
فقط محتوا را از یک نمایه فقط‌خواندنی و سرورهای فدراسیون بالادستی ارائه خواهد کرد، اما عملیات پویش یا پیراسته‌سازی را انجام نخواهد داد.

.SH "گزینه‌ها (OPTIONS)"

.TP
.B "\-F"
فعال‌سازی پویش فایل‌های ELF/DWARF. حالت پیش‌فرض غیرفعال است.

.TP
.B "\-Z EXT" "\-Z EXT=CMD"
فعال‌سازی یک الگوی اضافی در پویش آرشیوها. فایل‌های دارای پسوند نام EXT (شامل نقطه) پردازش خواهند شد. اگر CMD ارائه شده باشد، به همراه نام فایل که به فهرست آرگومان‌های آن افزوده شده اجرا می‌شود، و باید یک آرشیو معمولی را در خروجی استاندارد خود تولید کند. در غیر این صورت، فایل طوری خوانده می‌شود که گویی CMD برابر "cat" بوده است. از آنجا که debuginfod در درون خود از
\fBlibarchive\fP
برای خواندن فایل‌های آرشیو استفاده می‌کند، می‌تواند دامنه وسیعی از قالب‌های آرشیو و حالت‌های فشرده‌سازی را بپذیرد. حالت پیش‌فرض، بدون الگوی اضافی است. این گزینه می‌تواند تکرار شود.

.TP
.B "\-R"
فعال‌سازی الگوهای RPM در پویش آرشیوها. حالت پیش‌فرض غیرفعال است. معادل
\fB\%\-Z\~.rpm=cat\fP
است، زیرا libarchive می‌تواند به صورت بومی آرشیوهای RPM را پردازش کند. اگر نسخه libarchive شما بسیار قدیمی‌تر از سال ۲۰۲۰ است، توجه داشته باشید که برخی توزیع‌ها به فشرده‌سازی ناسازگار zstd برای محتوای بسته‌های خود تغییر وضعیت داده‌اند. در این صورت می‌توانید به جای
\fB\-R\fP
گزینه
\fB\%\-Z\ .rpm='(rpm2cpio|zstdcat)<'\fP
را بیازمایید.

.TP
.B "\-U"
فعال‌سازی الگوهای DEB/DDEB در پویش آرشیوها. حالت پیش‌فرض غیرفعال است. معادل
\fB\%\-Z\ .deb='(bsdtar\ \-O\ \-x\ \-f\ \-\ data.tar\\*)<\fP'
و به همین ترتیب برای
\fB.ddeb\fP
و
\fB.ipk\fP.

.TP
.B "\-d FILE" "\-\-database=FILE"
تنظیم مسیر پایگاه‌داده sqlite مورد استفاده برای ذخیره نمایه. این فایل از این جهت که یک پویش مجدد بعدی اطلاعات را بازسازی خواهد کرد، یک‌بارمصرف محسوب می‌شود. این فایل شامل مسیرهای مطلق فایل‌ها خواهد بود، بنابراین ممکن است میان سیستم‌های مختلف قابل‌انتقال نباشد. این فایل ممکن است مکرراً خوانده و نوشته شود، بنابراین باید روی یک سیستم فایل پرسرعت قرار گیرد. به منظور بیشینه‌سازی عملکرد قفل‌گذاری sqlite، نباید میان چندین سیستم یا کاربر به اشتراک گذاشته شود. برای آزمون‌های سریع می‌توان از رشته جادویی ":memory:" استفاده کرد تا یک پایگاه‌داده موقت فقط در حافظه رم به کار گرفته شود. فایل پایگاه‌داده پیش‌فرض
\%$HOME/.debuginfod.sqlite
است.

.TP
.B "\-\-passive"
تنظیم سرور روی حالت غیرفعال (passive)، به گونه‌ای که تنها به درخواست‌های وب‌سرویس (webapi)، از جمله مشارکت در فدراسیون پاسخ می‌دهد. این حالت هیچ‌گونه پویش یا پیراسته‌سازی انجام نمی‌دهد و بنابراین پایگاه‌داده sqlite را فقط به صورت خواندنی باز می‌کند. بدین ترتیب می‌توان یک پایگاه‌داده را با اطمینان میان یک سرور فعالِ پویشگر/پیراینده و چندین سرور غیرفعال به اشتراک گذاشت و بار سرویس‌دهی را تقسیم کرد. گزینه‌های الگوی آرشیو همچنان باید مشخص شوند تا debuginfod بتواند پسوندهای نام فایل را برای استخراج و باز کردن شناسایی کند.

.TP
.B "\-\-metadata\-maxtime=SECONDS"
اعمال محدودیت بر زمان اجرای پرس‌وجوهای متادیتا در وب‌سرویس. این پرس‌وجوها، به ویژه کاراکترهای جانشین گسترده "glob"، می‌توانند زمان زیادی ببرند و نتایج بسیار بزرگی تولید کنند. سرورهای عمومی ممکن است نیاز به کنترل نرخ و محدودسازی آن‌ها داشته باشند. محدودیت پیش‌فرض ۵ ثانیه است. مقدار ۰ این محدودیت را غیرفعال می‌کند.

.TP
.B "\-D SQL" "\-\-ddl=SQL"
اجرای دستور مشخص‌شده sqlite پس از باز شدن و مقداردهی اولیه پایگاه‌داده به عنوان DDL (زبان تعریف داده‌های SQL) اضافی. این گزینه ممکن است برای تنظیم دقیق pragmaها یا نمایه‌های مرتبط با کارایی مفید باشد. این گزینه می‌تواند تکرار شود. حالت پیش‌فرض بدون دستور اضافی است.

.TP
.B "\-p NUM" "\-\-port=NUM"
تنظیم شماره درگاه TCP (0 < NUM < 65536) که debuginfod باید برای پاسخگویی به درخواست‌های HTTP روی آن گوش فرا دهد. در صورت امکان، هر دو سوکت IPv4 و IPv6 باز می‌شوند. مستندات وب‌سرویس در ادامه آمده است. شماره درگاه پیش‌فرض 8002 است.

.TP
.B "\-\-listen\-address=ADDR"
تنظیم نشانی IP (آدرس IPv4/IPv6 سیستم) که debuginfod باید برای پاسخ به درخواست‌های HTTP روی آن گوش فرا دهد.

.TP
.B "\-\-cors"
افزودن هدرهای پاسخ مرتبط با CORS و پردازش متد OPTIONS. این امر به برنامه‌های تحت وب متفرقه اجازه می‌دهد داده‌های debuginfod را استعلام کنند، که ممکن است مطلوب باشد یا نباشد. مقدار پیش‌فرض خیر است.

.TP
.B "\-I REGEX"  "\-\-include=REGEX"  "\-X REGEX"  "\-\-exclude=REGEX"
کنترل شمول (include) و استثنا کردن (exclude) نام فایل‌ها در مسیرهای جستجو. عبارات باقاعده به عنوان عبارات باقاعده توسعه‌یافته POSIX بدون مهار (unanchored) تفسیر می‌شوند، بنابراین می‌توانند شامل تناوب (alternation) باشند. این عبارات در برابر مسیر کامل هر فایل بر اساس استانداردسازی
\fBrealpath(3)\fP
ارزیابی می‌شوند. به طور پیش‌فرض، تمامی فایل‌ها مشمول شده و هیچ فایلی مستثنی نمی‌شود. فایلی که هم با عبارت باقاعده شمول و هم با استثنا مطابقت داشته باشد، مستثنی خواهد شد. (\fIمحتویات\fP فایل‌های آرشیو مشمول فیلتر شمول یا استثنا نیستند: همگی پردازش می‌شوند.) تنها آخرین عبارت باقاعده ارائه‌شده از هر نوع به کار گرفته می‌شود.

.TP
.B "\-t SECONDS"  "\-\-rescan\-time=SECONDS"
تنظیم زمان پویش مجدد برای دایرکتوری‌های فایل و آرشیو. این مدت زمانی است که رشته پیمایشگر پس از پایان یک پویش، قبل از اجرای مجدد آن منتظر می‌ماند. پویش مجدد برای فایل‌های بدون تغییر بسیار سریع است (زیرا نمایه زمان آخرین ویرایش یا mtime فایل‌ها را نیز ذخیره می‌کند). زمان صفر نیز قابل‌قبول است و به این معناست که تنها یک بار پویش اولیه باید انجام شود. زمان پیش‌فرض پویش مجدد ۳۰۰ ثانیه است. دریافت سیگنال SIGUSR1 مستقل از زمان پویش مجدد (حتی اگر صفر باشد)، یک پویش جدید را آغاز کرده و دور پیراسته‌سازی (در صورت وجود) را متوقف می‌سازد.

.TP
.B "\-r"
اعمال گزینه‌های \-I و \-X در طول چرخه‌های پیراسته‌سازی (groom)، به گونه‌ای که بخش عمده محتوای مرتبط با فایل‌های مستثنی‌شده توسط عبارات باقاعده از نمایه حذف شوند. عملاً تمام محتوا قابل حذف نیست، بنابراین ممکن است در نهایت به یک عملیات پیراسته‌سازی حداکثری
.B "\-G"
(maximal-groom) نیاز باشد.

.TP
.B "\-g SECONDS" "\-\-groom\-time=SECONDS"
تنظیم زمان پیراسته‌سازی (groom) برای پایگاه‌داده نمایه. این مدت زمانی است که رشته پیراینده پس از پایان یک دور پیراسته‌سازی، پیش از آغاز دور بعدی منتظر می‌ماند. عملیات پیراسته‌سازی سریعاً تمام فایل‌های پیش‌تر پویش‌شده را بررسی می‌کند تا فقط ببیند آیا هنوز موجود و به‌روز هستند یا خیر، تا بتواند فایل‌های منسوخ‌شده را از نمایه حذف کند. همچنین بخش
\fIمدیریت داده‌ها (DATA MANAGEMENT)\fP
را ببینید. زمان پیش‌فرض پیراسته‌سازی ۸۶۴۰۰ ثانیه (۱ روز) است. زمان صفر نیز قابل‌قبول است و بدین معناست که تنها یک دور پیراسته‌سازی اولیه باید انجام پذیرد. دریافت سیگنال SIGUSR2 مستقل از زمان پیراسته‌سازی (حتی اگر صفر باشد)، یک دور پیراسته‌سازی جدید را آغاز کرده و دور پویش مجدد (در صورت وجود) را متوقف می‌سازد.

.TP
.B "\-G"
اجرای یک دور فوق‌العاده پیراسته‌سازی حداکثری (maximal-grooming) هنگام راه‌اندازی debuginfod. این دور می‌تواند زمان قابل‌توجهی ببرد، زیرا تلاش می‌کند هرگونه محتوای نامرتبط با debuginfo را از بخش‌های مرتبط با آرشیو در نمایه حذف کند. در صورتی که هرگونه عملیات نمایه‌سازی اخیر مرتبط با آرشیوها پیش از موعد متوقف شده باشد، این گزینه نباید اجرا شود. این عملیات می‌تواند فضای دیسک زیادی اشغال کند، زیرا در پایان یک عملیات "vacuum" در sqlite انجام می‌دهد که فایل پایگاه‌داده را با سه برابر کردن موقت حجم آن مجدداً فشرده و مرتب می‌کند. حالت پیش‌فرض عدم اجرای پیراسته‌سازی حداکثری است. همچنین بخش
\fIمدیریت داده‌ها (DATA MANAGEMENT)\fP
را ببینید.

.TP
.B "\-c NUM"  "\-\-concurrency=NUM"
تنظیم حد همروندی برای رشته‌های صف پویش، که با همکاری یکدیگر آرشیوها و فایل‌های پیدا شده توسط رشته پیمایشگر را پردازش می‌کنند. این گزینه برای کنترل عملیات‌های پرمصرف پردازنده مانند تجزیه فایل‌های ELF و به ویژه استخراج آرشیوها بسیار مهم است. مقدار پیش‌فرض وابسته به تعداد پردازنده‌های سیستم و سایر محدودیت‌هاست؛ حداقل مقدار ۱ است.

.TP
.B "\-C" "\-C=NUM" "\-\-connection\-pool" "\-\-connection\-pool=NUM"
تنظیم اندازه استخر رشته‌های پاسخ‌دهنده به پرس‌وجوهای وب‌سرویس. جدول زیر تفسیر این گزینه و پارامتر اختیاری NUM را خلاصه می‌کند:
.TS
l l.
بدون گزینه, \-C	استفاده از یک استخر رشته ثابت با اندازه خودکار
\-C=NUM	استفاده از یک استخر رشته ثابت با اندازه NUM، حداقل ۲
.TE

حالت اول یک پیکربندی ساده و امن مرتبط با تعداد پردازنده‌ها و سایر محدودیت‌ها است. حالت دوم برای پیکربندی‌های تنظیم‌شده جهت محدودسازی بار در مواجهه با ترافیک‌های مهارنشده مناسب است.

.TP
.B "\-L"
پیمایش پیوندهای نمادین مشاهده‌شده هنگام پیمایش PATHها، از جمله پیمایش میان دستگاه‌های مختلف \- مشابه
\fIfind\ \-L\fP.
حالت پیش‌فرض فقط پیمایش ساختار فیزیکی دایرکتوری، ماندن در همان دستگاه و نادیده گرفتن پیوندهای نمادین است \- مشابه
\fIfind\ \-P\ \-xdev\fP.
هشدار: وجود حلقه در درخت دایرکتوری نمادین ممکن است به
\fIپیمایش بی‌نهایت\fP
منجر شود.

.TP
.B "\-M LEVELS"  "\-\-max\-depth=LEVELS"
محدود کردن عمق پیمایش دایرکتوری به تعداد سطوح
\fILEVELS\fP
پایین‌تر از مسیرهای مبدأ \- همانند
\fIfind\ \-maxdepth\fP.
حالت پیش‌فرض عمق نامحدود است؛ حداقل مقدار ۰ است.

.TP
.B "\-\-fdcache\-mbs=MB"
پیکربندی محدودیت‌های حافظه پنهان (cache) که فایل‌های اخیراً استخراج‌شده از آرشیوها را نگه می‌دارد. تا سقف مجموع MB مگابایت به صورت استخراج‌شده نگهداری می‌شود تا از لزوم بازگشایی مکرر آرشیوهای آن‌ها جلوگیری شود. مقدار پیش‌فرض MB به میزان همروندی سیستم و فضای خالی دیسک در سیستم فایل $TMPDIR یا
\fB/tmp\fP
بستگی دارد (زیرا فایل‌های استخراج‌شده اخیر در آنجا نگهداری می‌شوند). در حالی که نسخه‌های قبلی از الگوریتم ساده LRU استفاده می‌کردند، اکنون حافظه پنهان تلاش می‌کند فایل‌های با دسترسی مکررتر و جدیدتر، و به ویژه فایل‌هایی که استخراج آن‌ها زمان زیادی برده است (مانند vdso.debug!) را نگهداری کند، و فایل‌های حجیم یا قدیمی را با اولویت کمتری نگه دارد.

.TP
.B "\-\-fdcache\-prefetch=NUM"
حداکثر به تعداد NUM فایل دیگر از یک آرشیو ممکن است پیش از آنکه حتی درخواست شوند، پیش‌واکشی (prefetch) شده و درون کش قرار گیرند. در صورت عدم تعیین، این مقادیر به همروندی سیستم و فضای در دسترس دیسک در $TMPDIR بستگی خواهد داشت. تخصیص مقادیر بیشتر، کارایی را در محیط‌هایی که بخش‌های مختلف چندین آرشیو بزرگ به طور همزمان مورد دسترسی قرار می‌گیرند، بهبود می‌بخشد.

.TP
.B "\-\-fdcache\-mintmp=NUM"
پیکربندی آستانه فضای دیسک برای تخلیه اضطراری حافظه‌های موقت (کش‌ها). سیستم فایلی که کش‌ها را در خود نگه می‌دارد به‌صورت دوره‌ای بررسی می‌شود. اگر فضای موجود به کمتر از درصد داده‌شده کاهش یابد، کش‌ها تخلیه می‌شوند و fdcaches تا چرخه پیراسته‌سازی بعدی غیرفعال خواهند ماند. این سازوکار به همراه چند سنجه در مسیر /metrics در وب‌سرویس، به منظور اطلاع‌رسانی به مدیر سیستم در خصوص کمبود فضای ذخیره‌سازی طراحی شده‌اند \- که اگر دیسک روی یک دیسک مجازی RAM قرار داشته باشد، می‌تواند به معنای کمبود RAM نیز باشد. آستانه پیش‌فرض 25% است.

.TP
.B "\-\-forwarded\-ttl\-limit=NUM"
پیکربندی محدودیت تعداد پرش‌های (hops) هدر X-Forwarded-For. اگر تعداد پرش‌های X-Forwarded-For از NUM تجاوز کند، در صورت نیافتن مورد در جستجوی محلی، درخواست به سرورهای debuginfod بالادستی محول نخواهد شد. حد پیش‌فرض ۸ است.

.TP
.B "\-\-disable\-source\-scan"
غیرفعال‌سازی پویش اطلاعات منبع DWARF در بخش‌های debuginfo. چنانچه در یک پیکربندی دسترسی به کدهای منبع وجود نداشته باشد، نیازی به اطلاعات منبع نخواهد بود.

.TP
.B "\-\-scan\-checkpoint=NUM"
اجرای عملیات همگام‌سازی نقطه بازرسی (checkpoint) در ژورنال WAL پایگاه‌داده SQLITE پس از هر NUM پویش کامل آرشیو یا فایل. این امر ممکن است تا حدی مرحله پویش موازی را کند نماید، اما در سرورهای شلوغ فایل‌های موقت "‎-wal" بسیار کوچک‌تری تولید خواهد کرد. مقدار پیش‌فرض ۲۵۶ است. با مقدار ۰ غیرفعال می‌شود.

.TP
.B "\-\-koji\-sigcache"
فعال‌سازی مرحله اضافی نگاشت مسیر RPM هنگام استخراج امضاها برای استفاده در اعتبارسنجی IMA به ازای هر فایل RPM در مخازن koji. امضاها به جای هدر اصلی RPM، از فایل‌های rpm.sig در Fedora koji sigcache بازیابی می‌شوند. اگر امضایی در فایل rpm.sig در sigcache یافت نشود، به عنوان راهکار جایگزین (fallback) از خود فایل RPM استفاده خواهد شد.

.TP
.B "\-\-home\-redirect"
امکان تغییر مسیر (redirect) به یک نشانی وب سفارشی در صورتی که کلاینت ریشه سند (document root) را درخواست کند.

.TP
.B "\-\-home\-html"
امکان ارائه یک پرونده سفارشی با نوع text/html در صورتی که کلاینت ریشه سند (document root) را درخواست نماید.

.TP
.B "\-v"
افزایش میزان جزئیات گزارش‌ها در توصیف‌کننده فایل خطای استاندارد (stderr). این گزینه می‌تواند برای افزایش جزئیات تکرار شود. مقدار پیش‌فرض 0 است.

.SH "وب‌سرویس (WEBAPI)"

وب‌سرویس (webapi) برنامه debuginfod شبیه به یک سرویس‌دهنده فایل معمولی عمل می‌کند، که در آن یک درخواست GET با مسیری حاوی یک buildid شناخته‌شده منجر به تحویل فایل می‌شود. ترکیب‌های ناشناخته از buildid یا نوع درخواست منجر به کدهای خطای HTTP می‌گردد. این شباهت به سرویس‌دهی فایل تعمدی است، تا بتوان در ساختار پیاده‌سازی‌شده از زیرساخت‌های استاندارد مدیریت HTTP بهره‌مند شد.
.PP
پس از یافتن یک فایل در آرشیو یا مستقیماً در پایگاه‌داده، تعدادی هدر سفارشی http به پاسخ افزوده می‌شود. برای فایل‌های موجود در پایگاه‌داده، هدرهای X-DEBUGINFOD-FILE و X-DEBUGINFOD-SIZE اضافه می‌شوند. هدر X-DEBUGINFOD-FILE صرفاً نام فایل اسکیپ‌نشده و X-DEBUGINFOD-SIZE اندازه فایل است. برای فایل‌هایی که در آرشیوها پیدا می‌شوند، علاوه بر X-DEBUGINFOD-FILE و X-DEBUGINFOD-SIZE، هدر X-DEBUGINFOD-ARCHIVE نیز اضافه می‌شود. هدر X-DEBUGINFOD-ARCHIVE نام آرشیوی است که فایل در آن پیدا شده است. هدر X-DEBUGINFOD-IMA-SIGNATURE نیز حاوی امضای IMA به ازای هر فایل به صورت داده باینری (blob) در قالب هگزادسیمال است.

.SAMPLE
% debuginfod-find -v debuginfo /bin/ls |& grep -i x-debuginfo
x-debuginfod-size: 502024
x-debuginfod-archive: /mnt/fedora_koji_prod/koji/packages/coreutils/9.3/4.fc39/x86_64/coreutils-debuginfo-9.3-4.fc39.x86_64.rpm
x-debuginfod-file: /usr/lib/debug/usr/bin/ls-9.3-4.fc39.x86_64.debug
.ESAMPLE

.TP
X-DEBUGINFOD-SIZE
اندازه فایل به بایت. این مقدار ممکن است به دلیل فشرده‌سازی در حین انتقال، با فیلد Content-Length پروتکل HTTP (در صورت وجود) متفاوت باشد.

.TP
X-DEBUGINFOD-FILE
نام مسیر کامل فایل مرتبط با buildid داده‌شده.

.TP
X-DEBUGINFOD-ARCHIVE
نام مسیر کامل آرشیوی که فایل فوق در آن قرار داشته است (در صورت وجود).
.PP
چندین نوع درخواست مرتبط با buildid وجود دارد. در هر مورد، buildid به صورت یک رشته هگزادسیمال با حروف کوچک کدگذاری می‌شود. برای مثال، برای برنامه‌ای مانند
\fI/bin/ls\fP،
بخش یادداشت ELF با عنوان GNU_BUILD_ID را بررسی کنید:

.SAMPLE
% readelf -n /bin/ls | grep -A4 build.id
Note section [ 4] '.note.gnu.buildid' of 36 bytes at offset 0x340:
Owner          Data size  Type
GNU                   20  GNU_BUILD_ID
Build ID: 8713b9c3fb8a720137a4a08b325905c7aaf8429d
.ESAMPLE
.PP
در این صورت BUILDID هگزادسیمال به سادگی برابر است با:

.SAMPLE
8713b9c3fb8a720137a4a08b325905c7aaf8429d
.ESAMPLE

.SS /buildid/\fIBUILDID\fP/debuginfo
اگر buildid داده‌شده برای سرور شناخته‌شده باشد، این درخواست به یک شیء باینری حاوی بخش‌های مرسوم
\fB.*debug_*\fP
منجر خواهد شد. این شیء ممکن است یک فایل مجزای debuginfo باشد که توسط
\fBstrip\fP
ایجاد شده، یا یک فایل اجرایی اصلی بدون تفکیک نمادها (unstripped) باشد.

.SS /buildid/\fIBUILDID\fP/executable
اگر buildid داده‌شده برای سرور شناخته‌شده باشد، این درخواست به یک شیء باینری منجر می‌شود که حاوی بخش‌های اجرایی معمول است. این فایل ممکن است یک فایل اجرایی باشد که نمادهایش توسط
\fBstrip\fP
حذف شده، یا یک فایل اجرایی اصلی بدون حذف نمادها باشد. کتابخانه‌های اشتراکی
\fBET_DYN\fP
نیز نوعی فایل اجرایی در نظر گرفته می‌شوند.

.SS /buildid/\fIBUILDID\fP/source\fI/SOURCE/FILE\fP
اگر buildid داده‌شده برای سرور شناخته‌شده باشد، این درخواست به یک شیء باینری حاوی فایل منبع اشاره‌شده منجر خواهد شد. مسیر باید مطلق باشد. نام مسیرهای نسبی معمولاً در دایرکتوری منبع فایل DWARF ظاهر می‌شوند، اما این مسیرها نسبت به مسیرهای AT_comp_dir هر واحد کامپایل (CU) هستند، در حالی که یک فایل اجرایی از چندین CU تشکیل شده است. از این رو، برای رفع ابهام، debuginfod انتظار دارد که در پرس‌وجوهای منبع، نام مسیرهای نسبی با دایرکتوری کامپایل CU و به دنبال آن یک "/" اجباری شروع شوند.
.PP
نکته: فراخواننده ممکن است مؤلفه‌های مسیری مانند
\fB../\fP
یا
\fB/./\fP
یا
\fB///\fPهای
اضافی را در نام دایرکتوری‌ها حذف کند یا نکند. دیمن debuginfod هر دو حالت را می‌پذیرد. به طور خاص، debuginfod نام مسیرها را بر اساس بخش 5.2.4 استاندارد RFC3986 (حذف بخش‌های نقطه‌دار) استانداردسازی می‌کند، و هرگونه
\fB//\fP
را در مسیر به
\fB/\fP
کاهش می‌دهد.
.PP
برای مثال:
.TS
l l.
#include <stdio.h>	/buildid/BUILDID/source/usr/include/stdio.h
/path/to/foo.c	/buildid/BUILDID/source/path/to/foo.c
\../bar/foo.c AT_comp_dir=/zoo/	/buildid/BUILDID/source/zoo//../bar/foo.c
.TE
.PP
نکته: کلاینت باید کاراکترهایی را در SOURCE/FILE/ که در بخش 2.3 استاندارد RFC3986 به عنوان "unreserved" نشان داده نشده‌اند، با درصد (%) اسکیپ کند. برخی از نویسه‌هایی که باید اسکیپ شوند عبارتند از "+"، "\\"، "$"، "!"، نویسه فاصله (' ') و "؛". استاندارد RFC3986 شامل فهرست جامع‌تری از این نویسه‌ها است.

.SS /buildid/\fIBUILDID\fP/section\fI/SECTION\fP
اگر buildid داده‌شده برای سرور شناخته‌شده باشد، سرور تلاش خواهد کرد محتویات یک بخش ELF/DWARF با نام SECTION را از فایل debuginfo منطبق با BUILDID استخراج کند. اگر فایل debuginfo پیدا نشود یا نوع بخش SHT_NOBITS باشد، سرور تلاش می‌کند آن بخش را از فایل اجرایی منطبق با BUILDID استخراج نماید. در صورت استخراج موفقیت‌آمیز بخش، این درخواست به یک شیء باینری از محتویات آن بخش منجر خواهد شد. توجه داشته باشید که این نتیجه، محتوای باینری خام آن بخش است، نه یک فایل کامل ELF.

.SS /metrics
این نقطه پایانی، خلاصه‌ای از انواع آمار و ارقام درباره عملکرد سرور debuginfod را با قالب متنی text/plain و با فرمت پرومتئوس (Prometheus) بازمی‌گرداند. مجموعه دقیق این سنجه‌ها و معانی آن‌ها ممکن است در نسخه‌های آینده تغییر یابد.

.SS /metadata?key=\fIKEY\fP&value=\fIVALUE\fP
این نقطه پایانی بر اساس کلید (key) و مقدار (value) داده‌شده، جستجویی را در میان فایل‌های موجود در نمایه و سرورهای فدراسیون بالادستی آغاز می‌کند. در صورت موفقیت، نتیجه یک آرایه متنی با ساختار application/json خواهد بود که متادیتای فایل‌های منطبق را فهرست می‌کند. برای مستندات مربوط به پارامترهای رایج جستجوی کلید/مقدار و شمای داده‌های حاصل، به
\fIdebuginfod\-find(1)\fP
مراجعه کنید.

.SH "مدیریت داده‌ها (DATA MANAGEMENT)"
دیمن debuginfod نمایه خود را در یک پایگاه‌داده sqlite در مجموعه‌ای متراکم از جدول‌های به هم پیوسته ذخیره می‌کند. در حالی که ساختار داده‌ها تا حد ممکن بهینه‌سازی شده است، اما هنوز ثبت تمام داده‌های مرتبط با debuginfo برای تعداد بالقوه بسیار زیادی از فایل‌ها به حجم داده قابل‌توجهی نیاز دارد. این بخش توصیه‌هایی درباره پیامدهای این موضوع ارائه می‌دهد.
.PP
به عنوان توضیحی کلی در مورد حجم، در نظر داشته باشید که وقتی debuginfod فایل‌های ELF/DWARF را نمایه‌سازی می‌کند، نام آن‌ها، نام فایل‌های منبع ارجاع‌شده و buildidها را ذخیره می‌نماید. هنگام نمایه‌سازی آرشیوها، نام هر فایل
\fIمتعلق به آرشیو یا درون\fP
آن، هر buildid، به علاوه نام هر فایل منبع ارجاع‌شده از یک فایل DWARF ذخیره می‌گردد. (نمایه‌سازی آرشیوها فضای بیشتری اشغال می‌کند زیرا فایل‌های منبع اغلب در زیربسته‌های جداگانه‌ای قرار دارند که ممکن است در همان دور نمایه‌سازی نشوند، بنابراین باید متادیتای اضافی نگهداری شود.)
.PP
اگر بخواهیم به ارقام و اعداد بپردازیم، در مورد بسته‌های RPM فدورا (که اساساً فایل‌های cpio فشرده‌شده با gzip هستند)، پایگاه‌داده نمایه sqlite تمایل دارد بین 0.5% تا 3% حجم آن‌ها باشد. این حجم برای فایل‌های باینری که از تعداد بسیار زیادی فایل منبع ساخته شده‌اند، یا بسته‌هایی که حامل محتوای نامرتبط زیادی با debuginfo هستند، بزرگ‌تر خواهد بود. این اندازه ممکن است در طول مرحله نمایه‌سازی به دلیل فایل‌های موقت ژورنال‌نویسی پیش‌رو (write-ahead-logging) در sqlite حتی بزرگ‌تر باشد؛ این فایل‌ها هنگام توقف برنامه همگام‌سازی (checkpointed) و پاکسازی می‌شوند. اعمال محدودیت‌های سخت‌گیرانه عبارت باقاعده
.B \-I
یا
.B \-X
برای مستثنی کردن فایل‌هایی که می‌دانید هیچ محتوای مرتبط با اطلاعات اشکال‌زدایی ندارند از روند پویش، می‌تواند بسیار مفید باشد.
.PP
هنگامی که debuginfod در حالت عادی
\fIفعال (active)\fP
اجرا می‌شود، به صورت دوره‌ای دایرکتوری‌های هدف خود را مجدداً پویش کرده و هر محتوای جدیدی را که بیابد به پایگاه‌داده اضافه می‌کند. محتوای قدیمی، مانند اطلاعات فایل‌هایی که حذف شده‌اند یا جای خود را به نسخه‌های جدیدتر داده‌اند، در یک دور دوره‌ای
\fIپیراسته‌سازی (grooming)\fP
حذف می‌گردد. این بدان معناست که فایل‌های sqlite در طول نمایه‌سازی اولیه به سرعت رشد می‌کنند، در طول پویش‌های مجدد نمایه رشدی آهسته دارند، و در زمان پیراسته‌سازی به صورت دوره‌ای کوچک می‌شوند. همچنین یک دور اختیاری و یک‌باره
\fIپیراسته‌سازی حداکثری (maximal grooming)\fP
نیز در دسترس است. این حالت داده‌های نامرتبط با debuginfo را از نمایه محتوای آرشیو حذف می‌کند، مانند نام فایل‌های پیدا شده در آرشیوها (رکوردهای "archive sdef") که به عنوان فایل‌های منبع توسط هیچ باینری موجود در آرشیوها ارجاع داده نشده‌اند (رکوردهای "archive sref"). این کار می‌تواند فضای قابل‌توجهی از دیسک را ذخیره کند. با این حال، کند است و موقتاً تا دو برابر اندازه پایگاه‌داده به فضای خالی نیاز دارد. بدتر از آن: اگر پیمایش آرشیوها متوقف شده باشد، ممکن است به دلیل مشخص نبودن تمامی ارجاعات فایل‌های منبع منجر به از دست رفتن اطلاعات کد منبع شود. از این گزینه به ندرت و صرفاً برای صیقل دادن یک نمایه کامل استفاده کنید.
.PP
باید اطمینان حاصل کنید که فضای کافی روی دیسک باقی مانده است. (سیل پیام‌های خطا در زمان اتمام فضای دیسک ‎-ENOSPC ناخوشایند و آزاردهنده است. با این وجود، همانند اکثر خطاهای دیگر، debuginfod به محض فراهم شدن منابع به کار خود ادامه خواهد داد.) در صورت لزوم، می‌توان debuginfod را متوقف کرد، فایل پایگاه‌داده را جابه‌جا یا حذف نمود، و سپس debuginfod را مجدداً راه‌اندازی کرد.
.PP
پایگاه‌داده sqlite گزینه‌های متعددی را در قالب pragmaها برای تنظیم کارایی ارائه می‌دهد. برخی از آن‌ها ممکن است برای تنظیم دقیق مقادیر پیش‌فرض و گزینه‌های اضافی debuginfod مفید باشند. گزینه
.B \-D
می‌تواند برای صدور دستور به debuginfod جهت اجرای قطعه کدهای مشخص‌شده SQL پس از دستورهای پایه‌ای ساخت شِما به کار رود. برای مثال، اگر در جستجوی حداکثر کارایی هستید، آزمودن pragmaهایی چون "synchronous"، "cache_size"، "auto_vacuum"، "threads" و "journal_mode" از طریق
.B \-D
می‌تواند جالب باشد. اجرای دوره‌ای pragmaهای "optimize" و "wal_checkpoint" در خارج از debuginfod نیز می‌تواند مفید واقع شود. تنظیمات پیش‌فرض بیش از آنکه مبتنی بر قابلیت اطمینان بالا باشند، مبتنی بر کارایی هستند؛ بنابراین یک توقف ناگهانی سخت‌افزاری ممکن است باعث خرابی پایگاه‌داده شود. در این شرایط، ممکن است لازم باشد پایگاه‌داده sqlite را به صورت دستی حذف کرده و دوباره از ابتدا شروع کنید.
.PP
همگام با تغییرات debuginfod در آینده، ممکن است چاره‌ای جز تغییر شمای پایگاه‌داده به شیوه‌ای ناسازگار با نسخه‌های قبلی وجود نداشته باشد. در صورت وقوع این امر، نسخه‌های جدید debuginfod دستورات SQL را برای
\fIحذف (drop)\fP
تمامی شِماها و داده‌های قبلی صادر کرده و کار را از ابتدا آغاز می‌کنند. بنابراین، فضای دیسک برای نگهداری مجموعه‌داده‌ای که دیگر قابل استفاده نیست به هدر نخواهد رفت.
.PP
به طور خلاصه، اگر سیستم شما می‌تواند نسبت حجم نمایه به آرشیو در حدود 0.5% تا 3% و رشد کند پس از آن را تاب بیاورد، نیازی به نگرانی درباره فضای دیسک نخواهید داشت. اگر نقص در سیستم باعث خرابی پایگاه‌داده شود یا بخواهید debuginfod را وادار به بازنشانی و شروع مجدد کنید، کافی است پیش از راه‌اندازی دوباره debuginfod، فایل sqlite را پاک کنید.
.PP
در مقابل، در حالت
\fIغیرفعال (passive)\fP،
تمامی عملیات‌های پویش و پیراسته‌سازی غیرفعال بوده و پایگاه‌داده نمایه در حالت فقط‌خواندنی باقی می‌ماند. این امر پایگاه‌داده را برای اشتراک‌گذاری میان سرورها یا سایت‌هایی با سازوکار همگام‌سازی یک‌طرفه مناسب‌تر می‌سازد، و ملاحظات مدیریت داده به طور کلی منتفی می‌شوند.

.SH "امنیت (SECURITY)"
برنامه debuginfod
\fBفاقد\fP
هرگونه ویژگی امنیتی خاص است. گرچه در برابر ورودی‌ها مقاوم است، اما احتمال برخی سوءاستفاده‌ها وجود دارد. این سرویس برای هر درخواست ورودی HTTP یک رشته (thread) جدید ایجاد می‌کند، که می‌تواند از نظر مصرف RAM، پردازنده، ورودی/خروجی دیسک یا شبکه منجر به حمله منع سرویس (DoS) شود. اگر این مسئله نگران‌کننده است، به کاربران توصیه می‌شود debuginfod را در پشت یک پراکسی معکوس (reverse-proxy) مبتنی بر HTTPS نصب کنند که سیاست‌های سایت را برای فایروال، احراز هویت، یکپارچگی، اعطای دسترسی و کنترل بار اعمال می‌نماید.
.PP
پراکسی‌های بخش کاربری (Front-end) ممکن است بخش‌های حساس نام مسیر را در هدرهای پاسخ X-DEBUGINFOD-FILE/ARCHIVE حذف کنند. برای مثال، با استفاده از ماژول
\fBmod_headers\fP
در وب‌سرور آپاچی، می‌توانید کل پیشوند نام دایرکتوری را حذف نمایید:

.SAMPLE
Header edit x-debuginfod-archive ".*/" ""
.ESAMPLE
.PP
هنگام بازپخش پرس‌وجوها به debuginfodهای بالادستی، debuginfod
\fBفاقد\fP
هرگونه ویژگی امنیتی خاص است. این برنامه اعتماد می‌کند که باینری‌های بازگردانده‌شده از سوی debuginfodها دقیق و معتبر هستند. بنابراین، فهرست سرورها تنها باید شامل سرورهای قابل‌اعتماد باشد. در صورت دسترسی از طریق پروتکل HTTP به جای HTTPS، شبکه انتقال باید کاملاً قابل‌اعتماد باشد. در حال حاضر اطلاعات احراز هویت از طریق کتابخانه داخلی
\fIlibcurl\fP
فعال نیست.

.nr zZ 1
.so man7/debuginfod-client-config.7

.SH "فایل‌های اضافی (ADDITIONAL FILES)"
.TP
.B $HOME/.debuginfod.sqlite
فایل پایگاه‌داده پیش‌فرض.
.PD


.SH "همچنین ببینید (SEE ALSO)"
.I "debuginfod-find(1)"
.I "sqlite3(1)"
.I \%https://prometheus.io/docs/instrumenting/exporters
.I \%https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS