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.