Skip to content

Update getting started document#1951

Open
shibukawa wants to merge 4 commits intocilium:mainfrom
shibukawa:patch-1
Open

Update getting started document#1951
shibukawa wants to merge 4 commits intocilium:mainfrom
shibukawa:patch-1

Conversation

@shibukawa
Copy link
Copy Markdown

Thank you for your grate product and effort.

https://packages.debian.org/search?keywords=llvm-strip&searchon=names&suite=all&section=all

https://packages.ubuntu.com/search?keywords=llvm-strip&searchon=names&suite=all&section=all

Both Debian and Ubuntu current versions don't have llvm-strip package and llvm seems to ship llvm-strip command.

Signed-off-by: Yoshiki Shibukawa <yoshiki@shibu.jp>
Added note about potential failure in virtualized environments when attaching the eBPF program to network interfaces. Explained the use of generic mode as an alternative.

Signed-off-by: Yoshiki Shibukawa <yoshiki@shibu.jp>
@shibukawa shibukawa requested a review from ti-mo as a code owner February 14, 2026 22:50
Signed-off-by: Yoshiki Shibukawa <yoshiki@shibu.jp>
Comment on lines +217 to +223
Note: On virtualized environments or network interfaces whose drivers do not
support native XDP, attaching may fail with "operation not supported".
In such cases, you can use generic mode instead:

Flags: link.XDPGenericMode

Generic mode has lower performance but works on a wider range of interfaces.
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not entirely sure if we want to encourage the usage of generic mode. XDP driver support for Virtio support exists since v4.10, and veth support since v4.19. A lot of more specialized virtual NICs have gained support in later kernels https://docs.ebpf.io/linux/program-type/BPF_PROG_TYPE_XDP/#driver-support.

So for the purposes of testing a user can always use a veth pair (via a container).

Generic mode has poor test coverage. So in production, when native XDP is not available, users should fallback to tc / BPF_PROG_TYPE_SCHED_CLS programs instead, which have broader capabilities, are better tested, and have comparable performance.

Long story short. I don't think this is advice we want to give people, especially not those that don't know any better.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Completely agree in principle, but with proper warnings attached, the user can make this decision on their own. The text you proposed is in a tooltip, though, so empty newlines break that. I'd make this an actual note below the Save this file as ... under the snippet.

!!! tip ""
    Some network interface drivers don't support native XDP, making this
    example fail with `operation not supported`. Try using generic mode by
    setting:
    
    ``` go
    Flags: link.XDPGenericMode
    ```
    
    Note that generic mode performs poorly and should not be used in production deployments.

Updated LLVM requirement to include 'llvm-strip' and clarified package distribution details.

Signed-off-by: Yoshiki Shibukawa <yoshiki@shibu.jp>
Refer to your distribution's package index to finding the right packages to
install, as this tends to vary wildly across distributions. Some
distributions ship `clang` and `llvm-strip` in separate packages.
distributions ship `clang` and `llvm-strip` in separate packages
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the pointer re: debian's llvm package. I just checked Fedora 44, and they also seem to ship llvm-strip in the llvm package (it's just a symlink to llvm-objcopy anyway, which is usually included). Let's remove the Some distributions ship... sentence altogether then, it'll just confuse new users.

Comment on lines +217 to +223
Note: On virtualized environments or network interfaces whose drivers do not
support native XDP, attaching may fail with "operation not supported".
In such cases, you can use generic mode instead:

Flags: link.XDPGenericMode

Generic mode has lower performance but works on a wider range of interfaces.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Completely agree in principle, but with proper warnings attached, the user can make this decision on their own. The text you proposed is in a tooltip, though, so empty newlines break that. I'd make this an actual note below the Save this file as ... under the snippet.

!!! tip ""
    Some network interface drivers don't support native XDP, making this
    example fail with `operation not supported`. Try using generic mode by
    setting:
    
    ``` go
    Flags: link.XDPGenericMode
    ```
    
    Note that generic mode performs poorly and should not be used in production deployments.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants