github.com/cilium/cilium@v1.16.2/bpf/custom/README.rst (about)

     1  ..  Copyright Authors of Cilium
     2  
     3  ===================================
     4  Tail Call Hooks for Custom Programs
     5  ===================================
     6  
     7  The files in this directory implement a sample byte-counter program which can
     8  be attached to dedicated hooks in the datapath.
     9  
    10  Note: This is a beta feature. Please provide feedback and file a GitHub issue
    11  if you experience any problems.
    12  
    13  Datapath Hooks
    14  ==============
    15  
    16  Implementation
    17  --------------
    18  
    19  When compiled with ``ENABLE_CUSTOM_CALLS`` set, Cilium's datapath contains some
    20  tail call hooks to insert custom programs in the datapath. These custom
    21  programs should be particularly careful *not* to interfere with the logics of
    22  the datapath, at the risk of altering or breaking the network connectivity in
    23  the cluster.
    24  
    25  Before the tail call happens, the datapath encodes two elements into the ``cb``
    26  field of the socket buffer for the packet:
    27  
    28  - The return value for that packet, so that the custom program can return it on
    29    exit. This is because a tail call is not like a function call, and the custom
    30    program does not *return* into the core datapath logics. Therefore, the
    31    custom program must be called as the very last step of the processing of the
    32    packet, and must preserve the return value selected by the datapath.
    33  
    34  - The remote security identity associated with the packet, that is, the Cilium
    35    identity associated with the sender for the ingress hook, and with the
    36    receiver when on the egress hook. This identity is not strictly necessary to
    37    the custom program, but it proved useful for some use cases. Given that the
    38    datapath already did the work for retrieving the identity for the packet, it
    39    just passes it down to the custom programs, in case it saves them the trouble
    40    to extract it a second time.
    41  
    42  Limitations
    43  -----------
    44  
    45  - There is currently no hook on the egress path for socket-level
    46    load-balancing.
    47  
    48  Sample Byte-Counter Program
    49  ============================
    50  
    51  This directory contains a sample byte-counter program, to help count how many
    52  bytes a given endpoint sends or receives, and to understand how the tail call
    53  hooks work.
    54  
    55  The following steps indicate how to use this example program.
    56  
    57  1. Compile the program. This should be easy thanks to the provided Makefile.
    58     From the root of the Cilium repository::
    59  
    60         $ make -C bpf/custom
    61  
    62  2. Load and pin the byte-counter program. Bpftool can do it::
    63  
    64         # bpftool prog load bpf/custom/bytecount.o \
    65             /sys/fs/bpf/tc/globals/bytecounter \
    66             type classifier \
    67             pinmaps /sys/fs/bpf/tc/globals/bytecounter_maps
    68  
    69  3. Pick the endpoint for which the program should count the bytes. Update the
    70     tail call map for custom programs for that endpoint, with a reference to the
    71     pinned byte-counter program::
    72  
    73         $ EP=<endpoint_id>
    74         # bpftool map update \
    75             pinned /sys/fs/bpf/tc/globals/cilium_calls_custom_$(printf '%05d' ${EP}) \
    76             key 0 0 0 0 \
    77             value pinned /sys/fs/bpf/tc/globals/bytecounter
    78  
    79     The key indicate the hook to use. It is possible to attach the program at
    80     multiple hooks, although the counter currently makes no distinction and will
    81     condensate the values collected from all hooks into a single counter. The
    82     available hooks and their keys are the following:
    83  
    84     - IPv4, ingress: ``key 0 0 0 0``
    85     - IPv4, egress:  ``key 1 0 0 0``
    86     - IPv6, ingress: ``key 2 0 0 0``
    87     - IPv6, egress:  ``key 3 0 0 0``
    88  
    89  4. After some traffic has flown, dump the content of the byte-counter map to
    90     read the statistics::
    91  
    92         # bpftool map dump \
    93             pinned /sys/fs/bpf/tc/globals/bytecounter_maps/bytecount_map
    94  
    95  5. When the byte-counter is no longer necessary, it is possible to clean it up
    96     by deleting the entry in the tail call map, and removing the pinned
    97     objects::
    98  
    99         # bpftool map delete \
   100             pinned /sys/fs/bpf/tc/globals/cilium_calls_custom_$(printf '%05d' ${EP}) \
   101             key 0 0 0 0
   102         # rm /sys/fs/bpf/tc/globals/custom_prog
   103         # rm -r /sys/fs/bpf/tc/globals/bytecounter_maps
   104  
   105  Using Other Custom Programs
   106  ===========================
   107  
   108  Other custom programs can be hooked into the datapath, just like the byte
   109  counter program. The workflow is similar.
   110  
   111  First, write a custom program, and make sure it does not interfere with the
   112  logics of the datapath. It is recommended to define a custom function and to
   113  include it in the “landing point” program from bpf_custom.c.
   114  
   115  Then, compile your program. If reusing bpf_custom.c, this is easy to do. The
   116  Makefile should use bpf_custom.c as a basis for compiling each .h header file
   117  found in the directory::
   118  
   119      $ make -C bpf/custom
   120  
   121  If you want to build a single program, just pass the name of the file
   122  containing the ``custom_prog`` function when calling make::
   123  
   124      $ BPF_CUSTOM_PROG_FILE=custom_function.h make -C bpf/custom
   125  
   126  The environment variable ``BPF_CUSTOM_PROG_NAME`` is similarly available to set
   127  the name of the ELF section where the resulting program will be located. This
   128  is often used to set either the program name, or, depending on the loading
   129  method, to indicate the type of the program to the loader. It will default to
   130  the base name (without the extension) of the .h file used to compile the
   131  program.