High-level SK_LOOKUP DSL for BPF programs.
SK_LOOKUP programs enable programmable socket lookup. When the kernel needs to find a socket for an incoming packet (e.g., TCP SYN or UDP), it typically searches listening sockets by IP/Port. SK_LOOKUP programs run before this search and can select a specific socket to receive the packet, bypassing standard bind rules.
Use cases:
Context: struct bpf_sk_lookup Return values:
The key helper is bpf_sk_assign which assigns a socket to handle the incoming connection.
Example: (defprogram my-sk-lookup :type :sk-lookup :license "GPL" :body (concat (sk-lookup-prologue :r6) ;; Check local port [(sk-lookup-load-field :r6 :r7 :local-port)] ;; If port 8080, assign to our socket [(dsl/jmp-imm :jne :r7 8080 5)] ;; ... load socket and assign ... (sk-lookup-pass)))
High-level SK_LOOKUP DSL for BPF programs.
SK_LOOKUP programs enable programmable socket lookup. When the kernel
needs to find a socket for an incoming packet (e.g., TCP SYN or UDP),
it typically searches listening sockets by IP/Port. SK_LOOKUP programs
run before this search and can select a specific socket to receive the
packet, bypassing standard bind rules.
Use cases:
- Bind multiple services to the same IP:port on different addresses
- Implement custom load balancing logic
- Service mesh socket steering
- Multi-tenant socket dispatch
Context: struct bpf_sk_lookup
Return values:
- SK_PASS (1): Continue with normal socket lookup
- SK_DROP (0): Drop the packet
The key helper is bpf_sk_assign which assigns a socket to handle
the incoming connection.
Example:
(defprogram my-sk-lookup
:type :sk-lookup
:license "GPL"
:body (concat
(sk-lookup-prologue :r6)
;; Check local port
[(sk-lookup-load-field :r6 :r7 :local-port)]
;; If port 8080, assign to our socket
[(dsl/jmp-imm :jne :r7 8080 5)]
;; ... load socket and assign ...
(sk-lookup-pass)))(build-sk-lookup-program {:keys [ctx-reg body default-action]
:or {ctx-reg :r6 default-action :pass}})Build a complete SK_LOOKUP program.
Parameters:
Returns assembled program bytes.
Build a complete SK_LOOKUP program. Parameters: - opts: Map with: :ctx-reg - Register to save context (default :r6) :body - Vector of body instructions :default-action - :pass or :drop (default :pass) Returns assembled program bytes.
(htonl value)Convert 32-bit value from host to network byte order (big-endian).
Parameters:
Returns network byte order value.
Convert 32-bit value from host to network byte order (big-endian). Parameters: - value: 32-bit integer Returns network byte order value.
(htons value)Convert 16-bit value from host to network byte order (big-endian).
Parameters:
Returns network byte order value.
Convert 16-bit value from host to network byte order (big-endian). Parameters: - value: 16-bit integer Returns network byte order value.
(ipv4-to-int ip-str)Convert IPv4 address string to integer.
Parameters:
Returns integer representation.
Convert IPv4 address string to integer. Parameters: - ip-str: IPv4 address string (e.g., "192.168.1.1") Returns integer representation.
(make-sk-lookup-info program-name instructions)Create program metadata for an SK_LOOKUP program.
Parameters:
Returns map with program metadata.
Create program metadata for an SK_LOOKUP program. Parameters: - program-name: Name for the BPF program - instructions: Program instructions Returns map with program metadata.
(ntohl value)Convert 32-bit value from network to host byte order.
Parameters:
Returns host byte order value.
Convert 32-bit value from network to host byte order. Parameters: - value: 32-bit integer in network byte order Returns host byte order value.
(ntohs value)Convert 16-bit value from network to host byte order.
Parameters:
Returns host byte order value.
Convert 16-bit value from network to host byte order. Parameters: - value: 16-bit integer in network byte order Returns host byte order value.
(sk-assign ctx-reg sk-reg flags)Generate instructions for bpf_sk_assign helper.
Assigns a socket to handle the incoming connection. The socket must be a listening socket obtained via bpf_sk_lookup_tcp or bpf_sk_lookup_udp, or from a SOCKMAP/SOCKHASH.
Parameters:
Helper signature: long bpf_sk_assign(struct bpf_sk_lookup *ctx, struct bpf_sock *sk, u64 flags)
Returns: 0 on success, negative error on failure
Returns vector of instruction bytes.
Generate instructions for bpf_sk_assign helper.
Assigns a socket to handle the incoming connection.
The socket must be a listening socket obtained via bpf_sk_lookup_tcp
or bpf_sk_lookup_udp, or from a SOCKMAP/SOCKHASH.
Parameters:
- ctx-reg: Register containing bpf_sk_lookup context
- sk-reg: Register containing socket pointer
- flags: Flags (usually 0)
Helper signature:
long bpf_sk_assign(struct bpf_sk_lookup *ctx,
struct bpf_sock *sk, u64 flags)
Returns:
0 on success, negative error on failure
Returns vector of instruction bytes.(sk-lookup-action action)Get SK_LOOKUP action value.
Parameters:
Returns integer value.
Get SK_LOOKUP action value. Parameters: - action: :drop (0) or :pass (1) Returns integer value.
(sk-lookup-assign-and-pass ctx-reg sk-reg)Generate instructions to assign socket and return SK_PASS.
Common pattern for SK_LOOKUP programs that select a socket.
Parameters:
Returns vector of instructions.
Generate instructions to assign socket and return SK_PASS. Common pattern for SK_LOOKUP programs that select a socket. Parameters: - ctx-reg: Register containing context pointer - sk-reg: Register containing socket pointer Returns vector of instructions.
(sk-lookup-check-port ctx-reg tmp-reg port skip-count)Generate instructions to check local port and branch.
Parameters:
Returns vector of instructions.
Generate instructions to check local port and branch. Parameters: - ctx-reg: Register containing context pointer - tmp-reg: Temporary register for port value - port: Port number to match (host byte order) - skip-count: Number of instructions to skip if port matches Returns vector of instructions.
(sk-lookup-check-protocol ctx-reg tmp-reg protocol skip-count)Generate instructions to check IP protocol and branch.
Parameters:
Returns vector of instructions.
Generate instructions to check IP protocol and branch. Parameters: - ctx-reg: Register containing context pointer - tmp-reg: Temporary register for protocol value - protocol: :tcp or :udp (or raw protocol number) - skip-count: Number of instructions to skip if protocol matches Returns vector of instructions.
(sk-lookup-drop)Generate instructions to drop the packet.
Returns SK_DROP (0).
Returns vector of instructions.
Generate instructions to drop the packet. Returns SK_DROP (0). Returns vector of instructions.
(sk-lookup-from-sockmap map-fd key-reg result-reg)Generate instructions to lookup socket from SOCKMAP by key.
Uses bpf_map_lookup_elem to get socket from SOCKMAP.
Parameters:
Note: This is a simplified pattern. For real use, you need to store the key on stack and pass a pointer to map_lookup_elem.
Returns vector of instruction bytes.
Generate instructions to lookup socket from SOCKMAP by key. Uses bpf_map_lookup_elem to get socket from SOCKMAP. Parameters: - map-fd: SOCKMAP file descriptor - key-reg: Register containing key (or will hold key after stack store) - result-reg: Register for result socket pointer Note: This is a simplified pattern. For real use, you need to store the key on stack and pass a pointer to map_lookup_elem. Returns vector of instruction bytes.
(sk-lookup-get-family ctx-reg dst-reg)Load protocol family from context.
Parameters:
Returns ldx instruction.
Load protocol family from context. Parameters: - ctx-reg: Register containing context pointer - dst-reg: Destination register Returns ldx instruction.
(sk-lookup-get-ifindex ctx-reg dst-reg)Load ingress interface index from context.
Parameters:
Returns ldx instruction.
Load ingress interface index from context. Parameters: - ctx-reg: Register containing context pointer - dst-reg: Destination register Returns ldx instruction.
(sk-lookup-get-local-ip4 ctx-reg dst-reg)Load local IPv4 address from context (network byte order).
Parameters:
Returns ldx instruction.
Load local IPv4 address from context (network byte order). Parameters: - ctx-reg: Register containing context pointer - dst-reg: Destination register Returns ldx instruction.
(sk-lookup-get-local-port ctx-reg dst-reg)Load local port from context (host byte order).
Parameters:
Returns ldx instruction.
Load local port from context (host byte order). Parameters: - ctx-reg: Register containing context pointer - dst-reg: Destination register Returns ldx instruction.
(sk-lookup-get-protocol ctx-reg dst-reg)Load IP protocol from context.
Parameters:
Returns ldx instruction.
Load IP protocol from context. Parameters: - ctx-reg: Register containing context pointer - dst-reg: Destination register Returns ldx instruction.
(sk-lookup-get-remote-ip4 ctx-reg dst-reg)Load remote IPv4 address from context (network byte order).
Parameters:
Returns ldx instruction.
Load remote IPv4 address from context (network byte order). Parameters: - ctx-reg: Register containing context pointer - dst-reg: Destination register Returns ldx instruction.
(sk-lookup-get-remote-port ctx-reg dst-reg)Load remote port from context (network byte order).
Parameters:
Returns ldx instruction.
Load remote port from context (network byte order). Parameters: - ctx-reg: Register containing context pointer - dst-reg: Destination register Returns ldx instruction.
(sk-lookup-load-field ctx-reg dst-reg field)Load a field from bpf_sk_lookup context.
Parameters:
Returns ldx instruction or vector of instructions.
Load a field from bpf_sk_lookup context. Parameters: - ctx-reg: Register containing context pointer - dst-reg: Destination register - field: Field keyword from sk-lookup-offsets Returns ldx instruction or vector of instructions.
(sk-lookup-offset field)Get offset for bpf_sk_lookup field.
Parameters:
Returns integer offset.
Get offset for bpf_sk_lookup field. Parameters: - field: Field keyword from sk-lookup-offsets Returns integer offset.
Offsets in bpf_sk_lookup context structure.
Note: All IP addresses and remote_port are in network byte order. local_port is in host byte order.
Offsets in bpf_sk_lookup context structure. Note: All IP addresses and remote_port are in network byte order. local_port is in host byte order.
(sk-lookup-pass)Generate instructions to pass (continue with normal/assigned socket).
Returns SK_PASS (1).
Returns vector of instructions.
Generate instructions to pass (continue with normal/assigned socket). Returns SK_PASS (1). Returns vector of instructions.
(sk-lookup-prologue ctx-save-reg)Generate SK_LOOKUP program prologue.
Saves the context pointer for later use.
Parameters:
Returns vector of instructions.
Generate SK_LOOKUP program prologue. Saves the context pointer for later use. Parameters: - ctx-save-reg: Register to save bpf_sk_lookup pointer Returns vector of instructions.
(sk-lookup-section-name)(sk-lookup-section-name name)Generate ELF section name for SK_LOOKUP program.
Returns "sk_lookup" or "sk_lookup/<name>".
Generate ELF section name for SK_LOOKUP program. Returns "sk_lookup" or "sk_lookup/<name>".
(sk-lookup-tcp ctx-reg tuple-ptr-reg tuple-size netns flags)Generate instructions for bpf_sk_lookup_tcp helper.
Looks up a TCP socket by 4-tuple. Returns socket pointer or NULL. The returned socket must be released with bpf_sk_release.
Parameters:
Returns vector of instruction bytes.
Generate instructions for bpf_sk_lookup_tcp helper. Looks up a TCP socket by 4-tuple. Returns socket pointer or NULL. The returned socket must be released with bpf_sk_release. Parameters: - ctx-reg: Register containing context pointer - tuple-ptr-reg: Register containing pointer to bpf_sock_tuple - tuple-size: Size of the tuple structure - netns: Network namespace (0 for current, or netns cookie) - flags: Lookup flags Returns vector of instruction bytes.
(sk-lookup-udp ctx-reg tuple-ptr-reg tuple-size netns flags)Generate instructions for bpf_sk_lookup_udp helper.
Looks up a UDP socket by 4-tuple. Returns socket pointer or NULL. The returned socket must be released with bpf_sk_release.
Parameters:
Returns vector of instruction bytes.
Generate instructions for bpf_sk_lookup_udp helper. Looks up a UDP socket by 4-tuple. Returns socket pointer or NULL. The returned socket must be released with bpf_sk_release. Parameters: - ctx-reg: Register containing context pointer - tuple-ptr-reg: Register containing pointer to bpf_sock_tuple - tuple-size: Size of the tuple structure - netns: Network namespace (0 for current, or netns cookie) - flags: Lookup flags Returns vector of instruction bytes.
SK_LOOKUP verdict return values.
SK_LOOKUP verdict return values.
(sk-release sk-reg)Generate instructions for bpf_sk_release helper.
Releases a socket reference obtained from bpf_sk_lookup_tcp/udp. Must be called for every socket obtained from lookup helpers.
Parameters:
Returns vector of instruction bytes.
Generate instructions for bpf_sk_release helper. Releases a socket reference obtained from bpf_sk_lookup_tcp/udp. Must be called for every socket obtained from lookup helpers. Parameters: - sk-reg: Register containing socket pointer Returns vector of instruction bytes.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |