نام (NAME)

bpftool-prog - ابزاری برای بازرسی و مدیریت برنامه‌های BPF

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

bpftool [OPTIONS] prog COMMAND

OPTIONS := { { -j | --json } [{ -p | --pretty }] | { -d | --debug } | { -f | --bpffs } | { -m | --mapcompat } | { -n | --nomount } | { -L | --use-loader } | [ { -S | --sign } -k <private_key.pem> -i <certificate.x509> ] }

COMMANDS := { show | list | dump xlated | dump jited | pin | load | loadall | help }

دستورات PROG (PROG COMMANDS)

bpftool prog { show | list } [PROG]
bpftool prog dump xlated PROG [{ file FILE | [opcodes] [linum] [visual] }]
bpftool prog dump jited  PROG [{ file FILE | [opcodes] [linum] }]
bpftool prog pin PROG FILE
bpftool prog { load | loadall } OBJ PATH [type TYPE] [map { idx IDX | name NAME } MAP] [{ offload_dev | xdpmeta_dev } NAME] [pinmaps MAP_DIR] [autoattach] [kernel_btf BTF_FILE]
bpftool prog attach PROG ATTACH_TYPE [MAP]
bpftool prog detach PROG ATTACH_TYPE [MAP]
bpftool prog tracelog
bpftool prog tracelog [ { stdout | stderr  } PROG ]
bpftool prog run PROG data_in FILE [data_out FILE [data_size_out L]] [ctx_in FILE [ctx_out FILE [ctx_size_out M]]] [repeat N]
bpftool prog profile PROG [duration DURATION] METRICs
bpftool prog help
MAP := { id MAP_ID | pinned FILE | name MAP_NAME }
PROG := { id PROG_ID | pinned FILE | tag PROG_TAG | name PROG_NAME }
TYPE := {
socket | kprobe | kretprobe | classifier | action |
tracepoint | raw_tracepoint | xdp | perf_event | cgroup/skb |
cgroup/sock | cgroup/dev | lwt_in | lwt_out | lwt_xmit |
lwt_seg6local | sockops | sk_skb | sk_msg | lirc_mode2 |
cgroup/bind4 | cgroup/bind6 | cgroup/post_bind4 | cgroup/post_bind6 |
cgroup/connect4 | cgroup/connect6 | cgroup/connect_unix |
cgroup/getpeername4 | cgroup/getpeername6 | cgroup/getpeername_unix |
cgroup/getsockname4 | cgroup/getsockname6 | cgroup/getsockname_unix |
cgroup/sendmsg4 | cgroup/sendmsg6 | cgroup/sendmsg_unix |
cgroup/recvmsg4 | cgroup/recvmsg6 | cgroup/recvmsg_unix | cgroup/sysctl |
cgroup/getsockopt | cgroup/setsockopt | cgroup/sock_release |
struct_ops | fentry | fexit | fsession | freplace | sk_lookup
}
ATTACH_TYPE := {
sk_msg_verdict | sk_skb_verdict | sk_skb_stream_verdict |
sk_skb_stream_parser | flow_dissector
}
METRICs := {
cycles | instructions | l1d_loads | llc_misses |
itlb_misses | dtlb_misses
}

توضیحات (DESCRIPTION)

bpftool prog { show | list } [PROG]

نمایش اطلاعات درباره برنامه‌های بارگذاری‌شده. اگر PROG مشخص شده باشد، اطلاعات فقط برای برنامه‌های داده‌شده نمایش داده می‌شود، در غیر این صورت تمام برنامه‌های بارگذاری‌شده فعلی در سیستم فهرست می‌شوند. در صورت استفاده از tag یا name، ممکن است PROG با چندین برنامه مطابقت داشته باشد که همگی نمایش داده خواهند شد.

خروجی با شناسه برنامه (ID) آغاز شده و به دنبال آن نوع برنامه و صفر یا چند ویژگی نام‌دار (بسته به نسخه هسته) درج می‌شود.

از لینوکس ۵.۱ به بعد، هسته می‌تواند آمار مربوط به برنامه‌های BPF را جمع‌آوری کند (مانند کل زمان صرف‌شده برای اجرای برنامه و تعداد دفعات اجرای آن). در صورت وجود، bpftool این آمار را نشان می‌دهد. با این حال، هسته به طور پیش‌فرض آن‌ها را جمع‌آوری نمی‌کند، زیرا تأثیر کمی بر کارایی هر بار اجرای برنامه می‌گذارد. فعال‌سازی یا غیرفعال‌سازی این ویژگی از طریق تنظیم sysctl با نام kernel.bpf_stats_enabled انجام می‌شود.

از لینوکس ۵.۸ به بعد، bpftool قادر است اطلاعات مربوط به فرآیندهایی را که توصیف‌کننده‌های فایل (FD) باز به برنامه‌های BPF دارند کشف کند. در چنین هسته‌هایی، bpftool به طور خودکار این اطلاعات را نیز منتشر می‌کند.

bpftool prog dump xlated PROG [{ file FILE | [opcodes] [linum] [visual] }]

دامپ (استخراج) دستورالعمل‌های eBPF برنامه‌ها از هسته. به طور پیش‌فرض، eBPF دیس‌اسمبل شده و در قالبی خوانا برای انسان در خروجی استاندارد چاپ می‌شود. در این حالت، opcodes کنترل می‌کند که آیا آپ‌کدهای خام (raw opcodes) نیز چاپ شوند یا خیر.

در صورت استفاده از tag یا name، ممکن است PROG با چندین برنامه مطابقت داشته باشد که همگی دامپ خواهند شد. با این حال، اگر file یا visual مشخص شده باشد، PROG باید تنها با یک برنامه مطابقت داشته باشد.

اگر file مشخص شده باشد، تصویر دودویی (binary image) به جای آن در FILE نوشته خواهد شد.

اگر visual مشخص شده باشد، به جای آن گراف جریان کنترل (CFG) ساخته می‌شود و دستورالعمل‌های eBPF همراه با CFG در قالب DOT در خروجی استاندارد ارائه می‌شوند.

اگر برنامه‌ها دارای line_info باشند، خط منبع کد نمایش داده می‌شود. در صورت مشخص شدن linum، نام فایل، شماره خط و ستون خط نیز نمایش داده خواهند شد.

bpftool prog dump jited PROG [{ file FILE | [opcodes] [linum] }]

دامپ تصویر کامپایل‌شده به روش JIT (کد ماشین میزبان) برنامه.

اگر FILE مشخص شده باشد تصویر در یک فایل نوشته می‌شود، در غیر این صورت دیس‌اسمبل شده و در stdout چاپ خواهد شد. هنگامی که file مشخص شده باشد، PROG باید تنها با یک برنامه مطابقت داشته باشد.

گزینه opcodes کنترل می‌کند که آیا آپ‌کدهای خام چاپ شوند یا خیر.

اگر برنامه دارای line_info باشد، خط منبع کد نمایش داده می‌شود. اگر linum مشخص شده باشد، نام فایل، شماره خط و ستون خط نیز نمایش داده خواهند شد.

bpftool prog pin PROG FILE

سنجاق کردن (pin) برنامه PROG با عنوان FILE.

نکته: FILE باید در یک نقطه سوارشده (mount) از bpffs قرار داشته باشد. این نام نباید شامل نویسه نقطه ('.') باشد، زیرا برای پسوندهای آینده در bpffs رزرو شده است.

bpftool prog { load | loadall } OBJ PATH [type TYPE] [map { idx IDX | name NAME } MAP] [{ offload_dev | xdpmeta_dev } NAME] [pinmaps MAP_DIR] [autoattach] [kernel_btf BTF_FILE]

بارگذاری برنامه‌(های) bpf از فایل دودویی OBJ و سنجاق کردن آن به عنوان PATH. دستور bpftool prog load تنها اولین برنامه موجود در OBJ را با عنوان PATH سنجاق می‌کند. دستور bpftool prog loadall تمام برنامه‌های درون OBJ را در دایرکتوری PATH سنجاق می‌کند. پارامتر type اختیاری است؛ اگر مشخص نشود، نوع برنامه از روی نام بخش‌ها (sections) استنتاج خواهد شد. به طور پیش‌فرض، bpftool نگاشت‌های جدیدی را بر اساس تعاریف موجود در آبجکت ELF در حال بارگذاری ایجاد می‌کند. پارامتر map امکان استفاده مجدد از نگاشت‌های موجود را فراهم می‌سازد. این پارامتر می‌تواند چندین بار، هر بار برای یک نگاشت متفاوت مشخص شود. IDX به اندیس نگاشتی که قرار است در فایل ELF جایگزین شود اشاره دارد (شمارش از ۰)، در حالی که NAME اجازه می‌دهد یک نگاشت با نام جایگزین شود. MAP نگاشت مورد استفاده را مشخص می‌کند و با id یا از طریق یک فایل سنجاق‌شده (pinned) به آن ارجاع داده می‌شود. اگر offload_dev NAME مشخص شود، برنامه روی دستگاه شبکه داده‌شده بارگذاری می‌شود (offload). اگر xdpmeta_dev NAME مشخص شود، برنامه بدون آف‌لود شدن مقید به دستگاه (device-bound) می‌شود که این کار دسترسی به متادیتای XDP را تسهیل می‌کند. آرگومان اختیاری pinmaps می‌تواند برای سنجاق کردن تمام نگاشت‌ها در دایرکتوری MAP_DIR ارائه شود.

اگر autoattach مشخص شده باشد، برنامه قبل از سنجاق شدن متصل (attach) خواهد شد. در این حالت، تنها پیوند (link - نمایانگر اتصال برنامه به قلاب مربوطه) سنجاق می‌شود و نه خود برنامه؛ بنابراین مسیر در bpftool prog show -f نمایش داده نخواهد شد و فقط در bpftool link show -f ظاهر می‌شود. همچنین، این ویژگی تنها زمانی کار می‌کند که bpftool (libbpf) قادر باشد تمام اطلاعات لازم را از فایل شیء استنتاج کند؛ به‌ویژه این قابلیت برای همه انواع برنامه‌ها پشتیبانی نمی‌شود. اگر برنامه‌ای از autoattach پشتیبانی نکند، bpftool برای آن برنامه به روش سنجاق کردن معمولی بازمی‌گردد.

گزینه kernel_btf امکان مشخص کردن یک فایل BTF خارجی را برای جایگزینی فایل BTF داخلی سیستم (vmlinux) جهت بازآرایی‌های CO-RE فراهم می‌کند. توجه داشته باشید که هر ویژگی دیگری که به BTF متکی است (مانند برنامه‌های fentry/fexit یا struct_ops) نیازمند فایل BTF مربوط به همان هسته واقعی در حال اجرا بر روی میزبان است که اغلب در مسیر /sys/kernel/btf/vmlinux در دسترس قرار دارد.

نکته: PATH باید در یک نقطه سوارشده از bpffs قرار داشته باشد. این مسیر نباید شامل نویسه نقطه ('.') باشد، زیرا برای پسوندهای آینده در bpffs رزرو شده است.

bpftool prog attach PROG ATTACH_TYPE [MAP]

متصل کردن (attach) برنامه bpf با نام PROG (با نوع مشخص‌شده توسط ATTACH_TYPE). اکثر انواع ATTACH_TYPE به پارامتر MAP نیاز دارند، به استثنای flow_dissector که به فضای نام شبکه فعلی متصل می‌شود.

bpftool prog detach PROG ATTACH_TYPE [MAP]

جدا کردن (detach) برنامه bpf با نام PROG (با نوع مشخص‌شده توسط ATTACH_TYPE). اکثر انواع ATTACH_TYPE به پارامتر MAP نیاز دارند، به استثنای flow_dissector که از فضای نام شبکه فعلی جدا می‌شود.

bpftool prog tracelog

دامپ لوله ردگیری (trace pipe) سیستم روی کنسول (stdout). برای متوقف کردن چاپ، کلیدهای <Ctrl+C> را فشار دهید. برنامه‌های BPF می‌توانند در زمان اجرا با استفاده از تابع کمکی bpf_trace_printk() در این لوله ردگیری بنویسند. این ویژگی تنها باید برای اهداف اشکال‌زدایی (debugging) استفاده شود. برای ارسال جریانی داده‌ها (streaming) از برنامه‌های BPF به فضای کاربر، می‌توان از رخدادهای perf استفاده کرد (همچنین به bpftool-map(8) مراجعه کنید).

bpftool prog tracelog { stdout | stderr } PROG

دامپ جریان BPF مربوط به برنامه. برنامه‌های BPF می‌توانند در زمان اجرا با استفاده از تابع هسته‌ای (kfunc) با نام bpf_stream_vprintk_impl() در این جریان‌ها بنویسند. هسته ممکن است پیام‌های خطا را در جریان خطای استاندارد بنویسد. این سازوکار تنها باید برای اهداف اشکال‌زدایی استفاده شود.

bpftool prog run PROG data_in FILE [data_out FILE [data_size_out L]] [ctx_in FILE [ctx_out FILE [ctx_size_out M]]] [repeat N]

اجرای برنامه BPF با نام PROG در زیرساخت آزمایشی هسته برای BPF؛ بدین معنی که برنامه روی داده‌ها و زمینه‌ای (context) که توسط کاربر فراهم شده کار می‌کند، نه روی بسته‌های واقعی یا توابع مانیتورشده و غیره. مقدار بازگشتی و مدت زمان اجرای آزمایشی روی کنسول چاپ می‌شود.

داده‌های ورودی از FILE ارائه‌شده با data_in خوانده می‌شود. اگر این FILE برابر با "-" باشد، داده‌های ورودی از ورودی استاندارد خوانده می‌شوند. زمینه ورودی (در صورت وجود)، از FILE ارائه‌شده با ctx_in خوانده می‌شود. مجدداً می‌توان از "-" برای خواندن از ورودی استاندارد استفاده کرد، اما تنها در صورتی که ورودی استاندارد قبلاً برای داده‌های ورودی به کار گرفته نشده باشد. اگر FILE با data_out مشخص شود، داده‌های خروجی در آن فایل نوشته می‌شوند. به همین ترتیب، زمینه خروجی در FILE ارائه‌شده با ctx_out نوشته می‌شود. برای هر دو جریان خروجی، می‌توان از "-" برای چاپ در خروجی استاندارد (به صورت متن ساده یا در صورت ارسال گزینه مربوطه به صورت JSON) استفاده کرد. اگر کلمات کلیدی خروجی حذف شوند، داده‌ها و زمینه خروجی دور ریخته می‌شوند. کلمات کلیدی data_size_out و ctx_size_out برای ارسال اندازه (به بایت) بافرهای خروجی به هسته استفاده می‌شوند، اگرچه مقدار پیش‌فرض ۳۲ کیلوبایت برای اکثر موارد بیش از اندازه کافی است.

کلمه کلیدی repeat برای مشخص کردن تعداد دفعات اجرای متوالی استفاده می‌شود. توجه داشته باشید که داده‌ها و زمینه خروجی نوشته‌شده در فایل‌ها مربوط به آخرین اجرا از این دفعات است. مدت زمان چاپ‌شده در پایان اجراها، میانگین تمام اجراهای انجام‌شده توسط دستور است.

همه انواع برنامه‌ها از اجرای آزمایشی پشتیبانی نمی‌کنند. در میان آن‌هایی که پشتیبانی می‌کنند نیز، همه نمی‌توانند آرگومان‌های ctx_in/ctx_out را بپذیرند. ابزار bpftool بررسی‌هایی روی انواع برنامه انجام نمی‌دهد.

bpftool prog profile PROG [duration DURATION] METRICs

پروفایل کردن معیارهای METRICs برای برنامه bpf با نام PROG به مدت DURATION ثانیه یا تا زمانی که کاربر کلیدهای <Ctrl+C> را فشار دهد. پارامتر DURATION اختیاری است. اگر DURATION مشخص نشود، پروفایل‌گیری تا UINT_MAX ثانیه ادامه خواهد یافت.

bpftool prog help

چاپ پیام راهنمای کوتاه.

گزینه‌ها (OPTIONS)

-h, --help: چاپ پیام راهنمای کوتاه (مشابه bpftool help).
-V, --version: چاپ شماره نسخه bpftool (مشابه bpftool version)، شماره نسخه libbpf در حال استفاده و ویژگی‌های اختیاری که هنگام کامپایل bpftool گنجانده شده‌اند. ویژگی‌های اختیاری شامل پیوند با LLVM یا libbfd برای ارائه دیس‌اسمبلر برای برنامه‌های JIT شده (bpftool prog dump jited) و استفاده از اسکلت‌های BPF (برخی ویژگی‌ها مانند bpftool prog profile یا نمایش pidهای مرتبط با شیءهای BPF ممکن است به آن وابسته باشند) است.
-j, --json: تولید خروجی به فرمت JSON. برای دستوراتی که نمی‌توانند JSON تولید کنند، این گزینه هیچ اثری ندارد.
-p, --pretty: تولید خروجی JSON با قالب‌بندی زیبا و خوانا برای انسان. متضمن -j است.
-d, --debug: چاپ تمام لاگ‌های موجود، حتی اطلاعات سطح اشکال‌زدایی (debug). این شامل لاگ‌های libbpf و همچنین بخش اعتبارسنج (verifier) در هنگام تلاش برای بارگذاری برنامه‌ها است.

-f, --bpffs: هنگام نمایش برنامه‌های BPF، نام فایل‌های برنامه‌های سنجاق‌شده نمایش داده شود.
-m, --mapcompat: اجازه دادن به بارگذاری نگاشت‌ها با تعاریف نگاشت ناشناخته.
-n, --nomount: عدم تلاش خودکار برای سوار کردن (mount) هرگونه فایل‌سیستم مجازی (مانند tracefs یا فایل‌سیستم مجازی BPF) در صورت نیاز.
-L, --use-loader: بارگذاری برنامه به عنوان یک برنامه «لودر» ("loader"). این گزینه برای اشکال‌زدایی در نحوه تولید چنین برنامه‌هایی مفید است. هنگامی که این گزینه استفاده می‌شود، bpftool سعی می‌کند برنامه‌ها را از فایل شیء در هسته بارگذاری کند، اما آن‌ها را سنجاق نمی‌کند (بنابراین PATH نباید ارائه شود).
هنگامی که با گزینه -d|--debug ترکیب شود، پیام‌های اشکال‌زدایی اضافی تولید می‌شوند و اجرای برنامه لودر از تابع کمکی bpf_trace_printk() برای ثبت هر مرحله از بارگذاری BTF، ایجاد نگاشت‌ها و بارگذاری برنامه‌ها استفاده خواهد کرد (به bpftool prog tracelog به عنوان روشی برای مشاهده و دامپ این پیام‌ها مراجعه کنید).
-S, --sign: فعال‌سازی امضای برنامه BPF قبل از بارگذاری. این گزینه باید همراه با -k و -i استفاده شود. استفاده از این فلگ به طور ضمنی --use-loader را فعال می‌کند.
-k <private_key.pem>: مسیر فایل کلید خصوصی در قالب PEM، هنگام امضا کردن الزامی است.
-i <certificate.x509>: مسیر فایل گواهی X.509 در قالب PEM یا DER، هنگام امضا کردن الزامی است.

مثال‌ها (EXAMPLES)

# bpftool prog show

10: xdp  name some_prog  tag 005a3d2123620c8b  gpl run_time_ns 81632 run_cnt 10
        loaded_at 2017-09-29T20:11:00+0000  uid 0
        xlated 528B  jited 370B  memlock 4096B  map_ids 10
        pids systemd(1)

# bpftool --json --pretty prog show

[{
        "id": 10,
        "type": "xdp",
        "tag": "005a3d2123620c8b",
        "gpl_compatible": true,
        "run_time_ns": 81632,
        "run_cnt": 10,
        "loaded_at": 1506715860,
        "uid": 0,
        "bytes_xlated": 528,
        "jited": true,
        "bytes_jited": 370,
        "bytes_memlock": 4096,
        "map_ids": [10
        ],
        "pids": [{
                "pid": 1,
                "comm": "systemd"
            }
        ]
    }
]

# bpftool prog dump xlated id 10 file /tmp/t
$ ls -l /tmp/t

-rw------- 1 root root 560 Jul 22 01:42 /tmp/t

# bpftool prog dump jited tag 005a3d2123620c8b

0:   push   %rbp
1:   mov    %rsp,%rbp
2:   sub    $0x228,%rsp
3:   sub    $0x28,%rbp
4:   mov    %rbx,0x0(%rbp)

# mount -t bpf none /sys/fs/bpf/
# bpftool prog pin id 10 /sys/fs/bpf/prog
# bpftool prog load ./my_prog.o /sys/fs/bpf/prog2
# ls -l /sys/fs/bpf/

-rw------- 1 root root 0 Jul 22 01:43 prog
-rw------- 1 root root 0 Jul 22 01:44 prog2

# bpftool prog dump jited pinned /sys/fs/bpf/prog opcodes

0:   push   %rbp
     55
1:   mov    %rsp,%rbp
     48 89 e5
4:   sub    $0x228,%rsp
     48 81 ec 28 02 00 00
b:   sub    $0x28,%rbp
     48 83 ed 28
f:   mov    %rbx,0x0(%rbp)
     48 89 5d 00

# bpftool prog load xdp1_kern.o /sys/fs/bpf/xdp1 type xdp map name rxcnt id 7
# bpftool prog show pinned /sys/fs/bpf/xdp1

9: xdp  name xdp_prog1  tag 539ec6ce11b52f98  gpl
        loaded_at 2018-06-25T16:17:31-0700  uid 0
        xlated 488B  jited 336B  memlock 4096B  map_ids 7

# rm /sys/fs/bpf/xdp1

# bpftool prog profile id 337 duration 10 cycles instructions llc_misses

   51397 run_cnt
40176203 cycles                                                 (83.05%)
42518139 instructions    #   1.06 insns per cycle               (83.39%)
     123 llc_misses      #   2.89 LLC misses per million insns  (83.15%)

خروجی زیر مربوط به لاگ‌های ردگیری (trace logs) است.
در ترمینال‌های جداگانه اجرا کنید:
# bpftool prog tracelog
# bpftool prog load -L -d file.o

bpftool-620059  [004] d... 2634685.517903: bpf_trace_printk: btf_load size 665 r=5
bpftool-620059  [004] d... 2634685.517912: bpf_trace_printk: map_create sample_map idx 0 type 2 value_size 4 value_btf_id 0 r=6
bpftool-620059  [004] d... 2634685.517997: bpf_trace_printk: prog_load sample insn_cnt 13 r=7
bpftool-620059  [004] d... 2634685.517999: bpf_trace_printk: close(5) = 0

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

bpf(2), bpf-helpers(7), bpftool(8), bpftool-btf(8), bpftool-cgroup(8), bpftool-feature(8), bpftool-gen(8), bpftool-iter(8), bpftool-link(8), bpftool-map(8), bpftool-net(8), bpftool-perf(8), bpftool-struct_ops(8), bpftool-token(8)