نام (NAME)

xdp-loader - بارگذار برنامه‌های XDP

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

ابزار XDP-loader یک بارگذار ساده برای برنامه‌های XDP است که از الصاق چندین برنامه به یک رابط شبکه یکسان پشتیبانی می‌کند. برای دستیابی به این هدف، قواعد معنایی بارگذاری و تخلیه ارائه‌شده توسط کتابخانه libxdp را پیاده‌سازی می‌کند. برای جزئیات نحوه کارکرد این ابزار و ویژگی‌های کرنل که به آن‌ها وابسته است، صفحه راهنمای libxdp(3) را مشاهده کنید.

اجرای xdp-loader

نحو اجرای xdp-loader به صورت زیر است:

xdp-loader COMMAND [options]
Where COMMAND can be one of:
       load        - load an XDP program on an interface
       unload      - unload an XDP program from an interface
       status      - show current XDP program status
       features    - show XDP features supported by the NIC
       clean       - clean up detached program links in XDP bpffs directory
       help        - show the list of available commands

هر دستور و گزینه‌های آن در ادامه توضیح داده شده است. همچنین می‌توانید از xdp-loader COMMAND --help برای مشاهده گزینه‌های هر دستور استفاده کنید.

دستور LOAD (The LOAD command)

دستور load یک یا چند برنامه XDP را روی یک رابط شبکه بارگذاری می‌کند.

نحو دستور load به صورت زیر است:

xdp-loader load [options] <ifname> <programs>

که در آن <ifname> نام رابط شبکه برای بارگذاری برنامه‌ها روی آن است، و <programs> یک یا چند نام فایل حاوی برنامه‌های XDP است. برنامه‌ها بر اساس اولویت مشخص‌شده در متادیتای برنامه (به libxdp(3) مراجعه کنید) روی رابط شبکه بارگذاری خواهند شد.

گزینه‌های پشتیبانی‌شده عبارتند از:

-m, --mode <mode>

حالتی را که برنامه XDP باید در آن بارگذاری شود مشخص می‌کند. مقادیر معتبر عبارتند از: 'native' که حالت پیش‌فرض XDP درون درایور است، 'skb' که از به اصطلاح حالت skb (معروف به XDP عمومی یا generic XDP) استفاده می‌کند، 'hw' که باعث برون‌سپاری برنامه به سخت‌افزار می‌شود، یا 'unspecified' که انتخاب حالت را به عهده کرنل می‌گذارد (کرنل در صورت پشتیبانی درایور حالت native و در غیر این صورت حالت generic را انتخاب خواهد کرد). توجه داشته باشید که استفاده از 'unspecified' پیش‌بینی حالت نهایی بارگذاری برنامه را دشوار می‌کند. به همین دلیل، پیش‌فرض 'native' است. توجه داشته باشید سخت‌افزارهایی که از حالت 'hw' پشتیبانی می‌کنند نادر هستند: کارت‌های Netronome/Corigine (با درایور 'nfp') تنها دستگاه‌های دارای پشتیبانی از این قابلیت در هسته اصلی لینوکس هستند.

-p, --pin-path <path>

یک مسیر ریشه را مشخص می‌کند که نگاشت‌های (maps) دارای ویژگی 'pinning' در تعاریف خود، زیر آن پین شوند. این مسیر باید روی یک سیستم فایل bpffs قرار داشته باشد. اگر تنظیم نشود، نگاشت‌ها پین نخواهند شد، حتی اگر ویژگی pinning را در تعاریف خود مشخص کرده باشند. هنگام پین کردن نگاشت‌ها، اگر مکان پین‌شده برای یک نگاشت از قبل وجود داشته باشد، در صورت سازگاری با نوع نگاشت در حال بارگذاری، نگاشت پین‌شده قبلی مجدداً استفاده خواهد شد.

-s, --section <section>

مشخص می‌کند که در هر فایل، برنامه(های) XDP از کدام بخش (section) فایل ELF بارگذاری شوند. پیش‌فرض استفاده از اولین برنامه در هر فایل است. اگر این گزینه تنظیم شود، برای تمام برنامه‌های در حال بارگذاری اعمال خواهد شد.

-n, --prog-name <prog_name>

مشخص می‌کند که در هر فایل، برنامه(های) XDP از کدام برنامه BPF با نام مشخص بارگذاری شوند. پیش‌فرض استفاده از اولین برنامه در هر فایل است. فقط یکی از گزینه‌های --section و --prog-name می‌تواند مشخص شود. اگر این گزینه تنظیم شود، برای تمام برنامه‌های در حال بارگذاری اعمال خواهد شد.

-P, --prio <priority>

اولویت بارگذاری برنامه(های) XDP را مشخص می‌کند (این گزینه بر ترتیب اجرای برنامه‌ها روی رابط شبکه تاثیر می‌گذارد). مقدار پیش‌فرض از متادیتای موجود در فایل ELF برنامه گرفته می‌شود، یا در صورت نبود متادیتا، مقدار ۵۰ در نظر گرفته می‌شود. اگر این گزینه تنظیم شود، برای تمام برنامه‌های در حال بارگذاری اعمال خواهد شد.

-A, --actions <actions>

«اقدامات فراخوانی زنجیره‌ای» (chain call actions) برنامه(های) XDP بارگذاری‌شده را مشخص می‌کند. این‌ها اقدامات XDP هستند که باعث می‌شوند برنامه بعدی بارگذاری‌شده روی رابط شبکه به جای بازگشت فوری فراخوانی شود. پیش‌فرض استفاده از مقدار تنظیم‌شده در متادیتای فایل ELF برنامه است، یا اگر چنین متادیتایی وجود نداشته باشد، مقدار XDP_PASS استفاده می‌شود. اگر این گزینه تنظیم شود، برای تمام برنامه‌های در حال بارگذاری اعمال خواهد شد.

-v, --verbose

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

-h, --help

نمایش خلاصه‌ای از گزینه‌های موجود

دستور UNLOAD (The UNLOAD command)

دستور unload برای تخلیه برنامه‌ها از یک رابط شبکه استفاده می‌شود.

نحو دستور unload به صورت زیر است:

xdp-loader unload [options] <ifname>

که در آن <ifname> نام رابط شبکه‌ای است که برنامه‌ها از آن تخلیه می‌شوند. برای مشخص کردن برنامه(هایی) که باید تخلیه شوند، باید از گزینه --all یا --id استفاده شود.

گزینه‌های پشتیبانی‌شده عبارتند از:

-i, --id <id>

تخلیه یک برنامه منفرد از رابط شبکه بر اساس شناسه (ID). برای دریافت شناسه برنامه مورد نظر جهت تخلیه، از xdp-loader status استفاده کنید. اگر این برنامه آخرین برنامه بارگذاری‌شده روی رابط شبکه باشد، برنامه توزیع‌کننده (dispatcher) نیز حذف خواهد شد که این عملیات را معادل مشخص کردن --all می‌سازد.

-a, --all

تخلیه تمام برنامه‌های XDP روی رابط شبکه، و همچنین حذف توزیع‌کننده چندبرنامه‌ای.

-v, --verbose

فعال‌سازی گزارش‌گیری اشکال‌زدایی. درج دوباره برای افزایش بیشتر سطح جزئیات.

-h, --help

نمایش خلاصه‌ای از گزینه‌های موجود

دستور STATUS (The STATUS command)

دستور status فهرستی از رابط‌های شبکه در سیستم و برنامه(های) XDP بارگذاری‌شده روی هر رابط را نمایش می‌دهد. برای هر رابط شبکه، فهرستی از برنامه‌ها به همراه اولویت اجرا و «اقدامات زنجیره‌ای» برای هر برنامه نشان داده می‌شود. برای مفهوم این متادیتا به بخش متادیتای برنامه مراجعه کنید.

-v, --verbose

فعال‌سازی گزارش‌گیری اشکال‌زدایی. درج دوباره برای افزایش بیشتر سطح جزئیات.

-h, --help

نمایش خلاصه‌ای از گزینه‌های موجود

دستور FEATURES (The FEATURES command)

دستور features قابلیت‌های XDP پشتیبانی‌شده توسط کارت شبکه (NIC) را نمایش می‌دهد.

قابلیت‌های XDP که در حال حاضر پشتیبانی می‌شوند عبارتند از:

NETDEV_XDP_ACT_BASIC

دستگاه شبکه از اجرای برنامه‌های XDP پشتیبانی پایه دارد و می‌تواند مجموعه کدهای بازگشتی پایه (XDP_ABORTED, XDP_DROP, XDP_PASS, XDP_TX) را مدیریت کند.

NETDEV_XDP_ACT_REDIRECT

دستگاه شبکه از مدیریت کد بازگشتی XDP_REDIRECT پشتیبانی می‌کند. این بدان معناست که بسته‌ها می‌توانند توسط XDP از این دستگاه بازهدایت شوند.

NETDEV_XDP_ACT_NDO_XMIT

رابط‌های شبکه بازخورد ndo_xdp_xmit را پیاده‌سازی می‌کنند. این به این معنی است که بسته‌ها می‌توانند توسط XDP به این دستگاه بازهدایت شوند.

NETDEV_XDP_ACT_XSK_ZEROCOPY

دستگاه شبکه از AF_XDP در حالت zero copy پشتیبانی می‌کند.

NETDEV_XDP_ACT_HW_OFFLOAD

دستگاه شبکه از برون‌سپاری سخت‌افزاری XDP پشتیبانی می‌کند.

NETDEV_XDP_ACT_RX_SG

دستگاه شبکه از فریم‌های غیرخطی XDP در سمت دریافت (RX) پشتیبانی می‌کند. این به این معناست که XDP می‌تواند با MTUهای بزرگ روی این دستگاه استفاده شود (در صورتی که برنامه XDP با پشتیبانی از fragments کامپایل شده باشد).

NETDEV_XDP_ACT_NDO_XMIT_SG

دستگاه شبکه از فریم‌های غیرخطی XDP در سمت ارسال (TX) پشتیبانی می‌کند. این بدان معناست که فریم‌های غیرخطی می‌توانند به این دستگاه بازهدایت شوند.

دستور CLEAN (The CLEAN command)

نحو دستور clean به صورت زیر است:

xdp-loader clean [options] [ifname]

دستور clean پیوندهای برنامه‌های جداشده (detached) در پوشه bpffs مربوط به XDP را پاکسازی می‌کند. هنگامی که یک رابط شبکه ناپدید می‌شود، هر برنامه‌ای که در حالت نرم‌افزاری (مانند skb یا native) بارگذاری شده باشد در پوشه bpffs پین‌شده باقی می‌ماند، اما ارتباط آن با رابط قطع می‌شود. این پیوندها باید از سیستم فایل حذف شوند. دستور clean یک پارامتر اختیاری نام رابط شبکه می‌گیرد تا تنها برنامه‌های جداشده مربوط به همان رابط را حذف کند. به طور پیش‌فرض، تمامی برنامه‌های جداشده برای تمام رابط‌ها حذف می‌شوند.

گزینه‌های پشتیبانی‌شده عبارتند از:

-v, --verbose

فعال‌سازی گزارش‌گیری اشکال‌زدایی. درج دوباره برای افزایش بیشتر سطح جزئیات.

-h, --help

نمایش خلاصه‌ای از گزینه‌های موجود

مثال‌ها (EXAMPLES)

برای بارگذاری یک برنامه XDP روی رابط eth0 کافیست دستور زیر را اجرا کنید:

# xdp-loader load eth0 xdp_drop.o
# xdp-loader status
CURRENT XDP PROGRAM STATUS:
Interface        Prio  Program name     Mode     ID   Tag               Chain actions
-------------------------------------------------------------------------------------
lo               <no XDP program>
eth0                   xdp_dispatcher   native   50   d51e469e988d81da
 =>              50    xdp_drop                  55   57cd311f2e27366b  XDP_PASS

خروجی نشان می‌دهد که یک برنامه توزیع‌کننده (dispatcher) روی رابط بارگذاری شده و برنامه xdp_drop به عنوان اولین (و تنها) مؤلفه بعد از آن نصب شده است. در این مورد، برنامه هیچ‌یک از متادیتای فوق را مشخص نکرده است، بنابراین مقادیر پیش‌فرض (اولویت ۵۰ و اقدام زنجیره‌ای XDP_PASS) اعمال شده‌اند.

برای استفاده از پین کردن خودکار نگاشت‌ها، ویژگی pinning را در تعریف نگاشت درون برنامه بگنجانید، مانند:

struct {
        __uint(type, BPF_MAP_TYPE_ARRAY);
        __uint(max_entries, 10);
        __type(key, __u32);
        __type(value, __u64);
        __uint(pinning, LIBBPF_PIN_BY_NAME);
} my_map SEC(".maps");

و آن را با گزینه --pin-path بارگذاری کنید:

# xdp-loader load eth0 my_prog.o --pin-path /sys/fs/bpf/my-prog

این دستور نگاشت را در مسیر /sys/fs/bpf/my-prog/my_map پین می‌کند. اگر این مسیر از قبل وجود داشته باشد، به جای ایجاد نگاشت جدید از همان نگاشت پین‌شده مجدداً استفاده می‌شود که این کار اجازه می‌دهد برنامه‌های مختلف BPF نگاشت را به اشتراک بگذارند.

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

برای جزئیات بیشتر در مورد قواعد معنایی بارگذاری XDP و نیازمندی‌های سازگاری کرنل به libxdp(3) مراجعه کنید.

گزارش باگ‌ها (BUGS)

لطفاً باگ‌ها را در گیت‌هاب گزارش دهید: https://github.com/xdp-project/xdp-tools/issues

نویسنده (AUTHOR)

ابزار xdp-loader و این صفحه راهنما توسط Toke Høiland-Jørgensen نوشته شده‌اند.