نام (NAME)

debuginfod-find - درخواست و دریافت فایلهای اشکالزدایی و کد منبع از سرورهای debuginfod

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

debuginfod-find [OPTION]... debuginfo BUILDID
debuginfod-find [OPTION]... debuginfo PATH
debuginfod-find [OPTION]... executable BUILDID
debuginfod-find [OPTION]... executable PATH
debuginfod-find [OPTION]... source BUILDID /FILENAME
debuginfod-find [OPTION]... source PATH /FILENAME
debuginfod-find [OPTION]... metadata KEY VALUE

توضیحات (DESCRIPTION)

دستور debuginfod-find یک یا چند سرور debuginfod را برای داده‌های مرتبط با اشکال‌زدایی (debuginfo) استعلام می‌کند. در صورت یافتن تطابق، پرونده درخواست‌شده را در یک حافظه موقت محلی (کَش) ذخیره کرده، نام پرونده را در خروجی استاندارد چاپ می‌کند و با وضعیت موفقیت 0 خارج می‌شود. در صورت بروز هرگونه خطا، با وضعیت شکست و صدور یک پیام خطا در خروجی خطای استاندارد پایان می‌یابد.

سامانه debuginfod از شناسه‌های ساخت (buildid) برای شناسایی داده‌های مرتبط با اشکال‌زدایی استفاده می‌کند. این شناسه‌ها به صورت یادداشت‌های باینری (binary notes) در پرونده‌های ELF/DWARF ذخیره شده و به صورت هگزادسیمال با حروف کوچک نشان داده می‌شوند. برای نمونه، برای برنامه /bin/ls، به یادداشت ELF با نام GNU_BUILD_ID نگاه کنید:

% 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

سپس BUILDID در مبنای شانزده به سادگی برابر است با:

8713b9c3fb8a720137a4a08b325905c7aaf8429d

به جای مقدار هگزادسیمال BUILDID، دستور debuginfod-find یک نام مسیر (PATH) به باینری ELF را نیز می‌پذیرد و شناسه ساخت را از آن استخراج می‌کند. این جایگزین در صورتی فعال می‌شود که نام پرونده دارای نویسه‌ای غیر از [0-9a-f] باشد. پرونده‌هایی با نام مبهم مانند "deadbeef" را می‌توان با یک جزء مسیر اضافی مانند ./deadbeef ارسال کرد.

debuginfo BUILDID

اگر buildid داده‌شده برای سرور شناخته‌شده باشد، این درخواست به یک شیء باینری منجر می‌شود که شامل بخش‌های معمول .*debug_* است. این پرونده ممکن است یک پرونده debuginfo تفکیک‌شده باشد که توسط strip ایجاد شده است، یا یک پرونده اجرایی اصلی بدون پیراستگی (unstripped).

executable BUILDID

اگر buildid داده‌شده برای سرور شناخته‌شده باشد، این درخواست به یک شیء باینری حاوی بخش‌های اجرایی معمول منتج می‌شود. این پرونده می‌تواند یک فایل اجرایی پیراسته‌شده توسط strip یا یک فایل اجرایی اصلی پیراسته‌نشده باشد. کتابخانه‌های اشتراکی ET_DYN نوعی فایل اجرایی در نظر گرفته می‌شوند.

source BUILDID /SOURCE/FILE

اگر buildid ارائه‌شده برای سرور شناخته‌شده باشد، این درخواست به یک شیء باینری منجر می‌شود که شامل پرونده منبع ذکرشده است. مسیر باید مطلق باشد. نام‌های مسیر نسبی معمولاً در دایرکتوری منبع پرونده DWARF دیده می‌شوند، اما این مسیرها نسبت به مسیرهای AT_comp_dir مربوط به هر واحد کامپایل منفرد (CU) سنجیده می‌شوند، در حالی که یک پرونده اجرایی از چندین CU تشکیل شده است. بنابراین، برای رفع ابهام، debuginfod انتظار دارد در پرس‌وجوهای فایل منبع، نام‌های مسیر نسبی دارای پیشوند دایرکتوری کامپایل CU باشند که به دنبال آن یک "/" اجباری آمده باشد.

نکته: برای نرم‌افزارهایی که توسط توزیع‌ها بسته‌بندی شده‌اند، دایرکتوری کامپایل CU ممکن است آشکار نباشد. این مسیر را می‌توان با بررسی مقادیر AT_comp_dir در debuginfo دانلودشده پیدا کرد. برای مثال، comp_dir نسخه فدورا ۳۷ برنامه /bin/ls را می‌توان به صورت زیر یافت:

% debuginfod-find debuginfo /bin/ls
~/.cache/debuginfod_client/03529d48345409576cd5c82a56ad08555088d353/
% eu-readelf -w ~/.cache/debuginfod_client/03529d48345409576cd5c82a56ad08555088d353/debuginfo | grep comp_dir
           comp_dir             (line_strp) "/usr/src/debug/coreutils-9.1-6.fc37.x86_64/separate"

نکته: فراخواننده ممکن است اجزای مسیر نظیر ../ یا /./ یا اسلش‌های اضافی /// را در نام دایرکتوری‌ها حذف کند یا نکند. سامانه debuginfod هر دو حالت را می‌پذیرد. به طور مشخص، debuginfod نام‌های مسیر را مطابق با RFC3986 بخش 5.2.4 (حذف بخش‌های نقطه‌دار) متعارف‌سازی کرده و علاوه بر آن هرگونه // را در مسیر به / تبدیل می‌کند.

برای مثال:

#include <stdio.h>	source BUILDID /usr/include/stdio.h
/path/to/foo.c	source BUILDID /path/to/foo.c
AT_comp_dir=/zoo/	source BUILDID /zoo//../bar/foo.c

section BUILDID SECTION-NAME

اگر buildid داده‌شده برای سرور شناخته‌شده باشد، این درخواست به یک پرونده باینری حاوی محتوای خام بخش (section) منجر می‌شود، چه در یک فایل اجرایی یافت شود و چه در یک پرونده debuginfo جداگانه.

metadata KEY VALUE

تمام سرورهای تعیین‌شده debuginfod برای متاداده‌های مربوط به همه پرونده‌هایی که با پرس‌وجوی کلید/مقدار داده‌شده در نمایه آن‌ها مطابقت دارند، استعلام می‌شوند. نتایج شامل نام‌ها و buildidها است که می‌توان در پرس‌وجوهای آینده برای دریافت فایل‌های واقعی استفاده کرد.

KEY	VALUE	DESCRIPTION
file	path	تطابق دقیق با path، از جمله درون آرشیوها
glob	pattern	تطابق الگوی سراسری شل با pattern، از جمله درون آرشیوها، همانند fnmatch(FNM_PATHNAME)
buildid	hex	تمام پرونده‌های اجرایی و اشکال‌زدایی منطبق با buildid داده‌شده

خروجی حاصل شبیه به موارد زیر خواهد بود:

{
  "results":[
    {
      "type":"executable",
      "buildid":"f0aa15b8aba4f3c28cac3c2a73801fefa644a9f2",
      "file":"/usr/local/bin/hello",
      "archive":"/opt/elfutils/tests/test-2290642/R/rhel7/hello2-1.0-2.x86_64.rpm"
    },
    {
      "type":"executable",
      "buildid":"bc1febfd03ca05e030f0d205f7659db29f8a4b30",
      "file":"hello2"
    }
  ],
  "complete":true
}

نتایج جستجو در stdout به صورت یک شیء JSON حاوی آرایه‌ای از اشیاء چاپ می‌شود که متاداده‌های مربوط به هر تطابق و همچنین یک مقدار بولی متناظر با کامل بودن نتیجه را ارائه می‌دهد. نتیجه در صورتی کامل تلقی می‌شود که تمامی پرس‌وجوها از سرورهای بالادستی نتایج کامل بازگردانده باشند و پرس‌وجوی محلی نیز موفقیت‌آمیز بوده باشد. این گزارش متاداده ممکن است کَش شود. این گزارش ممکن است ناقص باشد یا حاوی موارد تکراری باشد. همچنین فیلدهای شیء JSON اضافی نیز ممکن است وجود داشته باشند.

NAME	TYPE	DESCRIPTION
buildid	string	شناسه ساخت (buildid) هگزادسیمال مرتبط با پرونده
type	string	یکی از موارد debuginfo یا executable
file	string	نام پرونده منطبق‌شده، بیرون یا درون آرشیو
archive	string	آرشیو حاوی نام پرونده منطبق‌شده، در صورت وجود

شایان ذکر است که type نمی‌تواند source باشد، زیرا برای انجام چنین جستجویی با سرعت کافی، نیاز به افزودن نمایه‌سازی‌های اضافی به پایگاه‌داده خواهد بود که حجم آن را تقریباً دو برابر می‌کند.

همچنین این جستجو همیشه فایل‌ها و آرشیوها را در نتایج ترکیب می‌کند و در حال حاضر تفکیک دقیق‌تر در دسترس نیست.

گزینهها (OPTIONS)

-v --verbose: افزایش پرگویی (جزئیات خروجی)، از جمله چاپ مکرر پیام‌های پیشرفت دانلود و چاپ هدرهای پاسخ http از سرور.
--help --usage: چاپ پیام راهنما و خروج.

امنیت (SECURITY)

اگر امضا(های) IMA از RPMهای حاوی پرونده‌های درخواستی موجود باشند، در این صورت debuginfod آن امضاها را در هدرهای پاسخ استخراج می‌کند و debuginfod-find اعتبارسنجی را روی پرونده‌ها انجام خواهد داد. سیاست اعتبارسنجی از طریق تگ‌های درج‌شده درون $DEBUGINFOD_URLS کنترل می‌شود. به صورت پیش‌فرض، debuginfod-find در حالت چشم‌پوشی (ignore mode) عمل می‌کند.

اگر به جای HTTPS از طریق HTTP دسترسی برقرار شود، شبکه باید قابل‌اعتماد باشد. اطلاعات احراز هویت از طریق کتابخانه داخلی libcurl در حال حاضر فعال نیست، به جز سبک ساده و متن‌باز http[s]://userid:password@hostname. (سرور debuginfod احراز هویت را انجام نمی‌دهد، اما یک سرور پراکسی فرانت‌اند می‌تواند این کار را انجام دهد.)

See the file man7/debuginfod-client-config.7.

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

debuginfod(8) debuginfod_find_debuginfod(3)