Tsphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget&/translations/zh_CN/bpf/prog_sk_lookupmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/zh_TW/bpf/prog_sk_lookupmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/it_IT/bpf/prog_sk_lookupmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/ja_JP/bpf/prog_sk_lookupmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/ko_KR/bpf/prog_sk_lookupmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/sp_SP/bpf/prog_sk_lookupmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h2SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)h]h2SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhh@/var/lib/git/docbuild/linux/Documentation/bpf/prog_sk_lookup.rsthKubhsection)}(hhh](htitle)}(hBPF sk_lookup programh]hBPF sk_lookup program}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hBPF sk_lookup program type (``BPF_PROG_TYPE_SK_LOOKUP``) introduces programmability into the socket lookup performed by the transport layer when a packet is to be delivered locally.h](hBPF sk_lookup program type (}(hhhhhNhNubhliteral)}(h``BPF_PROG_TYPE_SK_LOOKUP``h]hBPF_PROG_TYPE_SK_LOOKUP}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubh~) introduces programmability into the socket lookup performed by the transport layer when a packet is to be delivered locally.}(hhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hWhen invoked BPF sk_lookup program can select a socket that will receive the incoming packet by calling the ``bpf_sk_assign()`` BPF helper function.h](hlWhen invoked BPF sk_lookup program can select a socket that will receive the incoming packet by calling the }(hhhhhNhNubh)}(h``bpf_sk_assign()``h]hbpf_sk_assign()}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubh BPF helper function.}(hhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh)}(hOHooks for a common attach point (``BPF_SK_LOOKUP``) exist for both TCP and UDP.h](h!Hooks for a common attach point (}(hj hhhNhNubh)}(h``BPF_SK_LOOKUP``h]h BPF_SK_LOOKUP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh) exist for both TCP and UDP.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(h Motivationh]h Motivation}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj-hhhhhKubh)}(hBPF sk_lookup program type was introduced to address setup scenarios where binding sockets to an address with ``bind()`` socket call is impractical, such as:h](hnBPF sk_lookup program type was introduced to address setup scenarios where binding sockets to an address with }(hj>hhhNhNubh)}(h ``bind()``h]hbind()}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj>ubh% socket call is impractical, such as:}(hj>hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj-hhubhenumerated_list)}(hhh](h list_item)}(hreceiving connections on a range of IP addresses, e.g. 192.0.2.0/24, when binding to a wildcard address ``INADRR_ANY`` is not possible due to a port conflict,h]h)}(hreceiving connections on a range of IP addresses, e.g. 192.0.2.0/24, when binding to a wildcard address ``INADRR_ANY`` is not possible due to a port conflict,h](hhreceiving connections on a range of IP addresses, e.g. 192.0.2.0/24, when binding to a wildcard address }(hjihhhNhNubh)}(h``INADRR_ANY``h]h INADRR_ANY}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjiubh( is not possible due to a port conflict,}(hjihhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjeubah}(h]h ]h"]h$]h&]uh1jchj`hhhhhNubjd)}(hRreceiving connections on all or a wide range of ports, i.e. an L7 proxy use case. h]h)}(hQreceiving connections on all or a wide range of ports, i.e. an L7 proxy use case.h]hQreceiving connections on all or a wide range of ports, i.e. an L7 proxy use case.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jchj`hhhhhNubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffix.uh1j^hj-hhhhhKubh)}(hSuch setups would require creating and ``bind()``'ing one socket to each of the IP address/port in the range, leading to resource consumption and potential latency spikes during socket lookup.h](h'Such setups would require creating and }(hjhhhNhNubh)}(h ``bind()``h]hbind()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh’ing one socket to each of the IP address/port in the range, leading to resource consumption and potential latency spikes during socket lookup.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj-hhubeh}(h] motivationah ]h"] motivationah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h Attachmenth]h Attachment}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK"ubh)}(hBPF sk_lookup program can be attached to a network namespace with ``bpf(BPF_LINK_CREATE, ...)`` syscall using the ``BPF_SK_LOOKUP`` attach type and a netns FD as attachment ``target_fd``.h](hBBPF sk_lookup program can be attached to a network namespace with }(hjhhhNhNubh)}(h``bpf(BPF_LINK_CREATE, ...)``h]hbpf(BPF_LINK_CREATE, ...)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh syscall using the }(hjhhhNhNubh)}(h``BPF_SK_LOOKUP``h]h BPF_SK_LOOKUP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh* attach type and a netns FD as attachment }(hjhhhNhNubh)}(h ``target_fd``h]h target_fd}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK$hjhhubh)}(h}Multiple programs can be attached to one network namespace. Programs will be invoked in the same order as they were attached.h]h}Multiple programs can be attached to one network namespace. Programs will be invoked in the same order as they were attached.}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK(hjhhubeh}(h] attachmentah ]h"] attachmentah$]h&]uh1hhhhhhhhK"ubh)}(hhh](h)}(hHooksh]hHooks}(hjHhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjEhhhhhK,ubh)}(hThe attached BPF sk_lookup programs run whenever the transport layer needs to find a listening (TCP) or an unconnected (UDP) socket for an incoming packet.h]hThe attached BPF sk_lookup programs run whenever the transport layer needs to find a listening (TCP) or an unconnected (UDP) socket for an incoming packet.}(hjVhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK.hjEhhubh)}(hIncoming traffic to established (TCP) and connected (UDP) sockets is delivered as usual without triggering the BPF sk_lookup hook.h]hIncoming traffic to established (TCP) and connected (UDP) sockets is delivered as usual without triggering the BPF sk_lookup hook.}(hjdhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK1hjEhhubh)}(hX7The attached BPF programs must return with either ``SK_PASS`` or ``SK_DROP`` verdict code. As for other BPF program types that are network filters, ``SK_PASS`` signifies that the socket lookup should continue on to regular hashtable-based lookup, while ``SK_DROP`` causes the transport layer to drop the packet.h](h2The attached BPF programs must return with either }(hjrhhhNhNubh)}(h ``SK_PASS``h]hSK_PASS}(hjzhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjrubh or }(hjrhhhNhNubh)}(h ``SK_DROP``h]hSK_DROP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjrubhH verdict code. As for other BPF program types that are network filters, }(hjrhhhNhNubh)}(h ``SK_PASS``h]hSK_PASS}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjrubh^ signifies that the socket lookup should continue on to regular hashtable-based lookup, while }(hjrhhhNhNubh)}(h ``SK_DROP``h]hSK_DROP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjrubh/ causes the transport layer to drop the packet.}(hjrhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK4hjEhhubh)}(hXA BPF sk_lookup program can also select a socket to receive the packet by calling ``bpf_sk_assign()`` BPF helper. Typically, the program looks up a socket in a map holding sockets, such as ``SOCKMAP`` or ``SOCKHASH``, and passes a ``struct bpf_sock *`` to ``bpf_sk_assign()`` helper to record the selection. Selecting a socket only takes effect if the program has terminated with ``SK_PASS`` code.h](hRA BPF sk_lookup program can also select a socket to receive the packet by calling }(hjhhhNhNubh)}(h``bpf_sk_assign()``h]hbpf_sk_assign()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhX BPF helper. Typically, the program looks up a socket in a map holding sockets, such as }(hjhhhNhNubh)}(h ``SOCKMAP``h]hSOCKMAP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh or }(hjhhhNhNubh)}(h ``SOCKHASH``h]hSOCKHASH}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh, and passes a }(hjhhhNhNubh)}(h``struct bpf_sock *``h]hstruct bpf_sock *}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh to }(hjhhhNhNubh)}(h``bpf_sk_assign()``h]hbpf_sk_assign()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhi helper to record the selection. Selecting a socket only takes effect if the program has terminated with }(hjhhhNhNubh)}(h ``SK_PASS``h]hSK_PASS}(hj*hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh code.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK:hjEhhubh)}(hWhen multiple programs are attached, the end result is determined from return codes of all the programs according to the following rules:h]hWhen multiple programs are attached, the end result is determined from return codes of all the programs according to the following rules:}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKAhjEhhubj_)}(hhh](jd)}(hwIf any program returned ``SK_PASS`` and selected a valid socket, the socket is used as the result of the socket lookup.h]h)}(hwIf any program returned ``SK_PASS`` and selected a valid socket, the socket is used as the result of the socket lookup.h](hIf any program returned }(hjWhhhNhNubh)}(h ``SK_PASS``h]hSK_PASS}(hj_hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjWubhT and selected a valid socket, the socket is used as the result of the socket lookup.}(hjWhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKDhjSubah}(h]h ]h"]h$]h&]uh1jchjPhhhhhNubjd)}(heIf more than one program returned ``SK_PASS`` and selected a socket, the last selection takes effect.h]h)}(heIf more than one program returned ``SK_PASS`` and selected a socket, the last selection takes effect.h](h"If more than one program returned }(hjhhhNhNubh)}(h ``SK_PASS``h]hSK_PASS}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh8 and selected a socket, the last selection takes effect.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKFhj}ubah}(h]h ]h"]h$]h&]uh1jchjPhhhhhNubjd)}(htIf any program returned ``SK_DROP``, and no program returned ``SK_PASS`` and selected a socket, socket lookup fails.h]h)}(htIf any program returned ``SK_DROP``, and no program returned ``SK_PASS`` and selected a socket, socket lookup fails.h](hIf any program returned }(hjhhhNhNubh)}(h ``SK_DROP``h]hSK_DROP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh, and no program returned }(hjhhhNhNubh)}(h ``SK_PASS``h]hSK_PASS}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh, and selected a socket, socket lookup fails.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKHhjubah}(h]h ]h"]h$]h&]uh1jchjPhhhhhNubjd)}(heIf all programs returned ``SK_PASS`` and none of them selected a socket, socket lookup continues on. h]h)}(hdIf all programs returned ``SK_PASS`` and none of them selected a socket, socket lookup continues on.h](hIf all programs returned }(hjhhhNhNubh)}(h ``SK_PASS``h]hSK_PASS}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh@ and none of them selected a socket, socket lookup continues on.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKJhjubah}(h]h ]h"]h$]h&]uh1jchjPhhhhhNubeh}(h]h ]h"]h$]h&]jjjhjjuh1j^hjEhhhhhKDubeh}(h]hooksah ]h"]hooksah$]h&]uh1hhhhhhhhK,ubh)}(hhh](h)}(hAPIh]hAPI}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKNubh)}(hIn its context, an instance of ``struct bpf_sk_lookup``, BPF sk_lookup program receives information about the packet that triggered the socket lookup. Namely:h](hIn its context, an instance of }(hj,hhhNhNubh)}(h``struct bpf_sk_lookup``h]hstruct bpf_sk_lookup}(hj4hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj,ubhg, BPF sk_lookup program receives information about the packet that triggered the socket lookup. Namely:}(hj,hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKPhjhhubh bullet_list)}(hhh](jd)}(h)IP version (``AF_INET`` or ``AF_INET6``),h]h)}(hjSh](h IP version (}(hjUhhhNhNubh)}(h ``AF_INET``h]hAF_INET}(hj\hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjUubh or }(hjUhhhNhNubh)}(h ``AF_INET6``h]hAF_INET6}(hjnhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjUubh),}(hjUhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKShjQubah}(h]h ]h"]h$]h&]uh1jchjNhhhhhNubjd)}(h`_ man-page section for ``bpf_sk_assign()`` for details.h](h Refer to }(hj'hhhNhNubh)}(h``struct bpf_sk_lookup``h]hstruct bpf_sk_lookup}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj'ubh declaration in }(hj'hhhNhNubh)}(h``linux/bpf.h``h]h linux/bpf.h}(hjAhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj'ubh user API header, and }(hj'hhhNhNubh reference)}(hL`bpf-helpers(7) `_h]hbpf-helpers(7)}(hjUhhhNhNubah}(h]h ]h"]h$]h&]namebpf-helpers(7)refuri8https://man7.org/linux/man-pages/man7/bpf-helpers.7.htmluh1jShj'ubhtarget)}(h; h]h}(h] bpf-helpers-7ah ]h"]bpf-helpers(7)ah$]h&]refurijfuh1jg referencedKhj'ubh man-page section for }(hj'hhhNhNubh)}(h``bpf_sk_assign()``h]hbpf_sk_assign()}(hj{hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj'ubh for details.}(hj'hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKYhjhhubeh}(h]apiah ]h"]apiah$]h&]uh1hhhhhhhhKNubh)}(hhh](h)}(hExampleh]hExample}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK_ubh)}(h\See ``tools/testing/selftests/bpf/prog_tests/sk_lookup.c`` for the reference implementation.h](hSee }(hjhhhNhNubh)}(h6``tools/testing/selftests/bpf/prog_tests/sk_lookup.c``h]h2tools/testing/selftests/bpf/prog_tests/sk_lookup.c}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh" for the reference implementation.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKahjhhubeh}(h]exampleah ]h"]exampleah$]h&]uh1hhhhhhhhK_ubeh}(h]bpf-sk-lookup-programah ]h"]bpf sk_lookup programah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjerror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(jjjjjBj?jjjjjrjojju nametypes}(jjjBjjjrjuh}(jhjj-j?jjjEjjjojijju footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages] transformerN include_log] decorationNhhub.