BPF，即Berkeley Packet Filter，是一个古老的网络封包过滤机制。它允许从用户空间注入一段简短的字节码到内核来定制封包处理逻辑。Linux从2.5开始移植了BPF，tcpdump就是基于BPF的应用。

所谓eBPF（extended BPF），则是从3.18引入的，对BPF的改造和功能增强：

1. 使用类似于X86的体系结构，eBPF设计了一个通用的RISC指令集，支持11个64bit寄存器（32bit子寄存器）r0-r10，使用512字节的栈空间
2. 引入了JIT编译，取代了BPF解释器。eBPF程序直接被编译为目标体系结构的机器码
3. 和网络子系统进行了解耦。它的数据模型是通用的，eBPF程序可以挂钩到

   Kprobe

   或

   Tracepoint

4. 使用Maps来存储全局数据，这是一种通用的键值存储。可用作不同eBPF程序、eBPF和用户空间程序的状态共享
5. 助手函数（Helper Functions），这些函数供eBPF程序调用，可以实现封包改写、Checksum计算、封包克隆等能力
6. 尾调用（Tail Calls），可以用于将程序控制权从一个eBPF转移给另外一个。老版本的eBPF对程序长度有4096字节的限制，通过尾调用可以规避
7. 用于Pin对象（Maps、eBPF程序）的伪文件系统
8. 支持将eBPF Offload给智能硬件的基础设施

以上增强，让eBPF不仅仅限于网络封包处理，当前eBPF的应用领域包括：

1. 网络封包处理：XDP、TC、socket progs、kcm、calico、cilium等
2. 内核跟踪和性能监控：KProbes、UProbes、TracePoints
3. 安全领域：Secomp、landlock等。例如阻止部分类型的系统调用

现在BPF一般都是指eBPF，而老的BPF一般称为cBPF（classic BPF）。

性能是eBPF的另外一个优势，由于所有代码都在内核空间运行，避免了复制数据到用户空间、上下文切换等开销。甚至编译过程都在尽可能的优化，例如助手函数会被内联到eBPF程序中，避免函数调用的开销。

用户提供的代码在内核中运行，安全性需要得到保证。eBPF校验器会对字节码进行各方面的检查，确保它不会导致内核崩溃或锁死。

eBPF具有非常好的灵活性、动态性，可以随时的注入、卸载，不需要重启内核或者中断网络连接。

eBPF程序可以在不同体系结构之间移植。

如上图所示，eBPF应用程序，从开发到运行的典型流程如下：

1. 利用Clang，将C语言开发的代码编译为eBPF object文件

2. 在用户空间将eBPF object文件载入内核。载入前，可能对object文件进行各种修改。这一步骤，可能通过iproute2之类的BPF ELF loader完成，也可能通过自定义的控制程序完成

3. BPF Verifier在VM中进行安全性校验

4. JIT编译器将字节码编译为机器码，返回BPF程序的文件描述符

5. 使用文件描述符将BPF程序挂钩到某个子系统（例如networking）的挂钩点。子系统有可能将BPF程序offload给硬件（例如智能网卡）

6. 用户空间通过eBPF Map和内核空间交换数据，获知eBPF程序的执行结果

eBPF程序以事件驱动的方式执行，具体来说，就是在内核的代码路径上，存在大量挂钩点（Hook Point）。eBPF程序会注册到某些挂钩点，当内核运行到挂钩点后，就执行eBPF程序。

挂钩点主要包括以下几类：

1. 网络事件，例如封包到达
2. Kprobes / Uprobes
3. 系统调用
4. 函数的入口/退出点

在加载之后，BPF校验器负责验证eBPF程序是否安全，它会模拟所有的执行路径，并且：

1. 检查程序控制流，发现循环
2. 检测越界的跳转、不可达指令
3. 跟踪Context的访问、栈移除
4. 检查unpriviledged的指针泄漏
5. 检查助手函数调用参数

在校验之后，eBPF程序被JIT编译器编译为Native代码。

键值对形式的存储，通过文件描述符来定位，值是不透明的Blob（任意数据）。用于跨越多次调用共享数据，或者与用户空间应用程序共享数据。

一个eBPF程序可以直接访问最多64个Map，多个eBPF程序可以共享同一Map。

BPF Maps和程序都是内核资源，仅能通过文件描述符访问到。文件描述符对应了内核中的匿名inodes。

用户空间程序可以使用大部分基于文件描述符的API，但是文件描述符是限制在进程的生命周期内的，这导致Map难以被共享。比较显著的例子是iproute2，当tc或XDP加载eBPF程序之后，自身会立刻退出。这导致无法从用户空间访问Map。

为了解决上面的问题，引入了一个最小化的、内核空间中的BPF文件系统。BPF程序和Map会被pin到一个被称为object pinning的进程。bpf系统调用有两个命令BPF_OBJ_PIN、BPF_OBJ_GET分别用于钉住、取回对象。

tc这样的工具就是利用Pinning在ingress/egress端共享Map。

尾调用允许一个BPF程序调用另外一个，这种调用没有函数调用那样的开销。其实现方式是long jump，重用当前stack frame。

注意：只用相同类型的BPF程序才能相互尾调用。

要使用尾调用，需要一个BPF_MAP_TYPE_PROG_ARRAY类型的Map，其内容目前必须由用户空间产生，值是需要被尾调用的BPF程序的文件描述符。通过助手函数bpf_tail_call触发尾调用，内核会将此调用内联到一个特殊的BPF指令。

BPF - BPF调用是一个新添加的特性。在此特性引入之前，典型的BPF C程序需要将所有可重用的代码声明为always_inline的，这样才能确保LLVM生成的object包含所有函数。这会导致函数在每个object文件中都反复（只要它被调用超过一次）出现，增加体积。

#include <linux/bpf.h>

#ifndef __section
# define __section(NAME)                  \
   __attribute__((section(NAME), used))
#endif

#ifndef __inline
# define __inline                         \
   inline __attribute__((always_inline))
#endif

// 总是内联
static __inline int foo(void)
{
    return XDP_DROP;
}

__section("prog")
int xdp_drop(struct xdp_md *ctx)
{
    return foo();
}

char __license[] __section("license") = "GPL";

总是需要内联的原因是BPF的Loader/Verifier/Interpreter/JITs不支持函数调用。但是从内核4.16和LLVM 6.0开始，此限制消除，BPF程序不再总是需要always_inline。上面程序的__inline可以去掉了。

目前x86_64/arm64的JIT编译器支持BPF to BPF调用，这是很重要的性能优化，因为它大大简化了生成的object文件的尺寸，对CPU指令缓存更加友好。

JIT编译器为每个函数生成独立的映像（Image），并且在JIT的最后一个步骤中修复映像中的函数调用地址。

到5.9为止，你不能同时使用BPF-BPF调用（BPF子程序）和尾调用。从5.10开始，可以混合使用，但是仍然存在一些限制。此外，混合使用两者可能导致内核栈溢出，原因是尾调用在跳转之前仅会unwind当前栈帧。

BPF网络程序，特别是tc和XDP，提供了将BPF代码offload给NIC执行的特性。这个特性需要驱动的支持。

能够加载BPF程序的前端工具有很多，包括bcc、perf、iproute2等。内核也在tools/lib/bpf目录下提供了用户空间库，被perf用来加载BPF追踪应用程序到内核。这是一个通用的库，你也可以直接调用它。BCC是面向追踪的工具箱。内核在samples/bpf下也提供了一些BPF示例，这些示例解析Object文件，并且直接通过系统调用将其载入内核。

基于不同前端工具，实现BPF程序的语法、语义（例如对于段名的约定）有所不同。

启用或禁用BPF JIT编译器：

0 仅用，仅仅使用解释器，默认值
1 启用JIT编译器
2 启用JIT编译器并且生成debugging trace到内核日志

设置为2，可以使用bpf_jit_disasm处理debugging trace

启用或禁用JIT加固，加固和性能是对立的，但是可以缓和JIT spraying：

0 禁用JIT加固，默认值
1 对非特权用户启用
2 对所有用户启用

启用或禁用JITed的程序的内核符号导出（导出到/proc/kallsyms），这样可以和perf工具一起使用，还能够让内核对BPF程序的地址感知（用于stack unwinding）：

0 启用
1 仅对特权用户启用

是否启用非特权的bpf系统调用。默认启用，一旦禁用，重启前无法恢复启用状态。不会影响seccomp等不使用bpf2系统调用的cBPF程序：

0 启用
1 禁用

eBPF程序可以调用助手函数，完成各种任务，例如：

1. 在Map中搜索、更新、删除键值对
2. 生成伪随机数
3. 读写隧道元数据
4. 尾调用 —— 将eBPF程序链在一起
5. 执行套接字相关操作，例如绑定、查询Cookies、重定向封包
6. 打印调试信息
7. 获取系统启动到现在的时间

助手函数是定义在内核中的，有一个白名单，决定哪些内核函数可以被eBPF程序调用。

根据eBPF的约定，助手函数的参数数量不超过5。

编译后，助手函数的代码是内联到eBPF程序中的，因而不存在函数调用的开销（栈帧处理开销、CPU流水线预取指令失效开销）。

返回int的类型的助手函数，通常操作成功返回0，否则返回负数。如果不是如此，会特别说明。

助手函数不可以随意调用，不同类型的eBPF程序，可以调用不同的助手函数子集。

iproute2提供的BPF前端，主要用来载入BPF网络程序，这些程序的类型包括XDP、tc、lwt。只要是为iproute2编写的BPF程序，共享统一的加载逻辑。

编译好的XDP类型（BPF_PROG_TYPE_XDP）的BPF程序 ，可以使用如下命令载入到支持XDP的网络设备：

ip link set dev eth0 xdp obj prog.o

上述命令假设程序位于名为prog的段中。如果不使用默认段名，则需要指定sec参数：

# 如果程序放在foobar段
ip link set dev em1 xdp obj prog.o sec foobar

如果程序没有标注段，也就是位于默认的.text段，则也可以用上面的命令加载。

如果已经存在挂钩到网络设备的XDP程序，默认情况下命令会报错，可以用-force参数强制替换：

ip -force link set dev em1 xdp obj prog.o

大多数支持XDP的驱动，能够原子的替换XDP程序，而不会引起流量中断。出于性能的考虑同时只能有一个XDP程序挂钩， 可以利用前文提到的尾调用来组织多个XDP程序。

如果网络设备挂钩了XDP程序，则ip link命令会显示xdp标记和程序的ID。使用bpftool传入ID可以查看更多细节信息。

ip link set dev eth0 xdp off

iproute2实现了XDP所支持的三种操作模式：

1. xdpdrv：即native XDP，BPF程序在驱动的接收路径的最早时刻被调用。这是正常的XDP模式，上游内核的所有主要10G/40G+网络驱动（包括virtio）都实现了XDP支持，也就是可使用该模式
2. xdpoffload：由智能网卡的驱动（例如Netronome的nfp驱动）实现，将整个XDP程序offload到硬件中，网卡每接收到封包都会执行XDP程序。该模式比native XDP的性能更高，缺点是，并非所有助手函数、Map类型可用。
3. xdpgeneric：即generic XDP，作为尚不支持native XDP的驱动的试验台。挂钩点比native XDP晚很多，已经进入网络栈的主接收路径，生成了skb对象，因此性能比native XDP差很多，不会用于生产环境

在切换驱动的XDP模式时，驱动通常需要重新配置它的接收/发送Rings，以保证接收到的封包线性的（linearly）存放到单个内存页中。

调用ip link set dev xxx xdp命令时，内核会首先尝试在native XDP模式下载入，如果驱动不支持，则自动使用generic XDP模式。要强制使用native XDP，则可以使用：

#                           强制使用native XDP
ip -force link set dev eth0 xdpdrv obj prog.o

使用类似的方式可以强制使用xdpgeneric、xdpoffload。

切换操作模式目前不能原子的进行，但是在单个操作模式下替换XDP程序则可以。

使用

verb

ip link set dev eth0 xdp obj xdp-example.o verb

除了从文件加载BPF程序，也可以直接从BPF伪文件系统中得到程序并使用：

ip link set dev eth0 xdp pinned /sys/fs/bpf/prog
#                               m:表示BPF文件系统的挂载点，默认/sys/fs/bpf/
ip link set dev eth0 xdp pinned m:prog

对于为tc设计的BPF程序（BPF_PROG_TYPE_SCHED_CLS、BPF_PROG_TYPE_SCHED_ACT），可以使用tc命令加载并挂钩到网络设备。和XDP不同，tc程序没有对驱动的依赖。

clsact

tc qdisc add dev eth0 clsact

clsact提供了两个特殊的钩子

ingress

egress

下面的命令，将BPF程序挂钩到eth0的ingress路径上：

tc filter add dev eth0 ingress bpf da obj prog.o

下面的命令将BPF程序挂钩到eth0的egress路径上：

tc filter add dev eth0 egress bpf da obj prog.o 

ingress钩子在内核中由

__netif_receive_skb_core() -> sch_handle_ingress()

egress钩子在内核中由

__dev_queue_xmit() -> sch_handle_egress()

clsact是以无锁方式处理的，支持挂钩到虚拟的、没有队列概念的网络设备，例如veth。

da

类似XDP，如果不使用默认的段名，需要用sec选项：

tc filter add dev eth0 egress bpf da obj prog.o sec foobar

已经挂钩到设备的tc程序的列表，可以用下面的命令查看：

tc filter show dev em1 ingress
filter protocol all pref 49152 bpf

     # 针对的L3协议    优先级      分类器类型  分类器句柄
filter protocol all    pref 49152 bpf        handle 0x1 
  # 从prog.o的ingress段加载了程序
  prog.o:[ingress] 
  # BPF程序运行在da模式
  direct-action 
  # 程序ID是全局范围唯一的BPF程序标识符，可以被bpftool使用
  id 1 
  # 程序指令流的哈希，哈希可以用来关联到Object文件，perf报告栈追踪的时候使用此哈希
  tag c5f7825e5dac396f


tc filter show dev em1 egress
filter protocol all pref 49152 bpf
filter protocol all pref 49152 bpf handle 0x1 prog.o:[egress] direct-action id 2 tag b2fd5adc0f262714

tc可以挂钩多个BPF程序，这和XDP不同，它提供了多个其它的、可以链接在一起的classifier。尽管如此，单个da模式的BPF程序可以满足所有封包操作需求，它可以直接返回action断言，例如

TC_ACT_OK

TC_ACT_SHOT

除非打算自动替换挂钩的BPF程序，建议初次挂钩时明确的指定pref和handle，这样，在后续手工替换的时候就不需要查询获取pref、handle：

tc filter add dev eth0 ingress pref 1 handle 1 bpf da obj prog.o sec foobar

使用下面的命令原子的替换BPF程序：

tc filter replace dev eth0 ingress pref 1 handle 1 bpf da obj prog.o sec foobar

要移除所有以及挂钩的BPF程序，执行：

tc filter del dev eth0 ingress
tc filter del dev eth0 egress

要从网络设备上移除整个clsact qdisc，可以：

tc qdisc del dev eth0 clsact

类似于XDP程序，tc程序也支持offload给职能网卡。你需要首先启用hw-tc-offload：

ethtool -K eth0 hw-tc-offload on

然后再启用clsact并挂钩BPF程序。XDP和tc的offloading不能同时开启。

内核提供了一个dummy驱动netdevsim，它实现了XDP/tc BPF的offloading接口，用于测试目的。

下面的命令可以启用netdevsim设备：

modprobe netdevsim
echo "1 1" > /sys/bus/netdevsim/new_device
devlink dev
# netdevsim/netdevsim1
devlink port
# netdevsim/netdevsim1/0: type eth netdev eth0 flavour physical
ip l
# 4: eth0: <BROADCAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000
#     link/ether 2a:d5:cd:08:d1:3f brd ff:ff:ff:ff:ff:ff

在网络封包处理方面，出现过一种提升性能的技术 —— 内核旁路（Kernel Bypass ）：完全在用户空间实现网络驱动和整个网络栈，避免上下文切换、内核网络层次、中断处理。具体实现包括Intel的DPDK （Data Plane Development Kit）、Cisco的VPP等。

内核旁路技术的缺点是：

1. 作为硬件资源的抽象层，内核是经过良好测试和验证的。在用户空间重新实现驱动，稳定性、可复用性欠佳
2. 实现网络栈也是困难的
3. 作为一个沙盒，网络处理程序难以和内核其它部分集成/交互
4. 无法使用内核提供的安全层

eXpress Data Path，为内核提供了一个基于eBPF的、高性能的、可编程的、运行在驱动层的封包处理框架，它提升性能的思路和内核旁路技术相反 —— 完全在内核空间实现封包处理逻辑，例如过滤、映射、路由等。XDP通过在网络接收路径的最早期挂钩eBPF程序来实现高速封包过滤。最早期意味着：NIC驱动刚刚从receiver rings接收到封包，任何高成本操作，例如分配skb并将封包推入网络栈，尚未进行。

XDP的起源来自于对DDoS攻击的防范。Cloudflare依赖（leverages heavily on）iptables进行封包过滤，在配置相当好的服务器上，可以处理1Mpps的流量。但是当出现DDoS攻击时，流量会高达3Mpps，这会导致Linux系统overflooded by IRQ请求，直到系统变得不稳定。

由于Cloudflare希望继续使用iptables以及其它内核网络栈功能，它不考虑使用DPDK这样的完全控制硬件的方案，而是使用了所谓部分内核旁路（partial kernel bypass），NIC的一部分队列继续附到内核，另外一部分队列则附到一个用户空间应用程序，此程序决定封包是否应该被丢弃。通过在网络栈的最底部就决定是否应该丢弃封包，需要经由内核网络子系统的封包数量大大减少了。

Cloudflare利用了Netmap工具包实现部分内核旁路。但是这个思路可以延伸为，在内核网络栈中增加一个Checkpoint，这个点应该离NIC接收到封包的时刻尽可能的近。这个Checkpoint将把封包交给用户编写的程序，决定是应该丢弃，还是继续正常处理路径。

XDP对应的BPF程序类型是：BPF_PROG_TYPE_XDP。XDP程序可以读写封包，调用助手函数解析封包、计算Checksum，这些操作都不会牵涉系统调用的开销（都在内核空间执行）。

尽管XDP的基本用途是，尽早的决定封包是否应该丢弃。但是，由于网络函数无非是读、写、转发、丢弃等原语的组合，XDP可以用来实现任何网络功能。

XDP的主要优势包括：

1. 可以使用各种内核基础设施，例如路由表、套接字、网络栈
2. 运行在内核中，使用和内核其它部分一致的安全模型
3. 运行在内核中，不需要跨越用户/内核空间边界，能够灵活的转发封包给其它内核实体，例如命名空间、网络栈
4. 支持动态替换XDP程序，不会引起网络中断
5. 保证封包的线性（linearly）布局，封包位于单个DMAed内存页中，访问起来很方便
6. 保证封包有256字节可用的额外headroom，可以用于（使用助手函数

   bpf_xdp_adjust_head

   、

   bpf_xdp_adjust_meta

   ）添加自定义的封装包头

从内核4.8+开始，主要发行版中XDP可用，大部分10G+网络驱动支持XDP。

XDP的高性能特征，让它非常适合实现DDoS攻击缓解，以及一般性防火墙。

BPF程序可以对封包进行任意的修改，甚至是通过助手函数任意的增减headroom大小实现封装/解封装。

处理完的封包通过XDP_REDIRECT动作即可转发封包给其它NIC，或者转发给其它CPU（利用BPF的cpumap）

使用XDP_TX动作，hairpinned LB可以将修改后的封包从接收它的网卡发送回去。

XDP支持将部分或截断的封包内容存放到无锁的per-CPU的内存映射ring buffer中。此ring buffer由Linux perf基础设施提供，可以被用户空间访问。

在XDP中，代表当前封包的结构是：

struct xdp_buff {
    // 内存页中，封包数据的开始点指针
    void *data;
    // 内存页中，封包数据的结束点指针
    void *data_end;
    // 最初和和data指向同一位置。后续可以被bpf_xdp_adjust_meta()调整，向data_hard_start方向移动
    // 可以用于为元数据提供空间。这种元数据对于正常的内核网络栈是不可见的，但是能够被tc BPF程序读取，
    // 因为元数据会从XDP传送到skb中
    // data_meta可以仅仅适用于在尾调用之间传递信息，类似于可被tc访问的skb->cb[]
    void *data_meta;
    // XDP支持headroom，这个字段给出页中，此封包可以使用的，最小的地址
    // 如果封包被封装，则需要调用bpf_xdp_adjust_head()，将data向data_hard_start方向移动
    // 解封装时，也可以使用bpf_xdp_adjust_head()移动指针
    void *data_hard_start;
    // 提供一些额外的per receive queue元数据，这些元数据在ring setup time生成
    struct xdp_rxq_info *rxq;
};

// 接收队列信息
struct xdp_rxq_info {
    struct net_device *dev;
    u32 queue_index;
    u32 reg_state;
} ____cacheline_aligned; // 缓存线（默认一般是64KB），CPU以缓存线为单位读取内存到CPU高速缓存

它通过BPF context传递给XDP程序。

enum xdp_action {
    // 提示BPF出现错误，和DROP的区别仅仅是会发送一个trace_xdp_exception追踪点
    XDP_ABORTED = 0,
    // 应当在驱动层丢弃封包，不必再浪费额外资源。对于DDos缓和、一般性防火墙很有用
    XDP_DROP,
    // 允许封包通过，进入网络栈进行常规处理
    // 处理此封包的CPU后续将分配skb，将封包信息填充进去，然后传递给GRO引擎
    XDP_PASS,
    // 将封包从接收到的网络接口发送回去，可用于实现hairpinned LB
    XDP_TX,
    // 重定向封包给另外一个NIC
    XDP_REDIRECT,
};

这个枚举是XDP程序需要返回的断言，告知驱动应该如何处理封包。

关于tc的基础知识，参考基于tc的网络QoS管理。

BPF可以和内核的tc层一起工作。tc程序和XDP程序有以下不同：

1. tc程序的BPF输入上下文是skb_buff，而非xdp_buff。在XDP之后，内核会解析封包，存入skb_buff。解析的开销导致tc程序的性能远低于XDP，但是，tc程序可以访问skb的mark, pkt_type, protocol, priority, queue_mapping, napi_id, cb[]数组, hash, tc_classid, tc_index等字段，以及VLAN元数据、XDP传送来的自定义元数据。BPF上下文

   struct __sk_buff

   定义在

   linux/bpf.h

2. tc程序可以挂钩到ingress/egress网络路径上，XDP则仅仅能挂钩到ingress路径
3. tc程序对驱动层没有依赖，可以挂钩到任何类型的网络设备。除非启用tc BPF程序的offloading

尽管tc程序的挂钩点没有XDP那么早，但是仍然是在内核网络路径的早期。它在GRO运行之后，任何协议处理之前执行。iptables PREROUTING、nftables ingress hook等工具也在相同的位置挂钩。

工作在tc层的BPF程序，是从一个名为

cls_bpf

过滤器cls_bpf可以挂钩1-N个BPF程序，当有多个BPF程序情况下，前面的程序返回verdict

TC_ACT_UNSPEC

cls_bpf有一个direct-action（da）模式，这样BPF程序能够直接返回action verdict，决定封包命运，结束tc处理流水线。

tc BPF程序也支持在运行时动态更新，而不会中断任何网络流量。

cls_bpf可以挂钩到的ingress/egress钩子，均被一个伪（不在qdisc树形结构中）排队规则

sch_clsact

__dev_queue_xmit()

典型情况下，egress方向会有附到网络设备的qdisc，例如sch_htb、sch_fq，它们其中有些是classful qdisc。classful qdisc会通过

tcf_classify()

为了达到最大性能（减少锁争用），可以考虑这样的用法：使用sch_clsact + cls_bpf，在root qdisc锁之外，完成任务繁重的封包分类工作，并且设置skb->mark或skb->priority。然后，由运行在root qdisc锁下的sch_htb快速的根据skb字段完成分类、塑形操作。

sch_clsact + cls_bpf组合使用时，如果cls_bpf是da模式、只包含单个BPF程序、且位于ingress网络路径，则支持offload给智能网卡。

在tc BPF程序中，代表当前封包的结构是

__sk_buff

sk_buff

struct __sk_buff {
	__u32 len;
	__u32 pkt_type;
	__u32 mark;
	__u32 queue_mapping;
	__u32 protocol;
	__u32 vlan_present;
	__u32 vlan_tci;
	__u32 vlan_proto;
	__u32 priority;
	__u32 ingress_ifindex;
	__u32 ifindex;
	__u32 tc_index;
	__u32 cb[5];
	__u32 hash;
	__u32 tc_classid;
	__u32 data;
	__u32 data_end;
	__u32 napi_id;

	/* Accessed by BPF_PROG_TYPE_sk_skb types from here to ... */
	__u32 family;
	__u32 remote_ip4;	/* Stored in network byte order */
	__u32 local_ip4;	/* Stored in network byte order */
	__u32 remote_ip6[4];	/* Stored in network byte order */
	__u32 local_ip6[4];	/* Stored in network byte order */
	__u32 remote_port;	/* Stored in network byte order */
	__u32 local_port;	/* stored in host byte order */
	/* ... here. */

	__u32 data_meta;
	__bpf_md_ptr(struct bpf_flow_keys *, flow_keys);
	__u64 tstamp;
	__u32 wire_len;
	__u32 gso_segs;
	__bpf_md_ptr(struct bpf_sock *, sk);
};

tc ingress/egress钩子能够返回的verdict定义在：

// 未指定，如果有多个BPF程序，会继续运行下一个。如果没有更多BPF程序
// 则提示内核在没有任何side-effect的情况下继续处理skb
#define TC_ACT_UNSPEC         (-1)
// 从tc BPF程序角度，TC_ACT_OK、TC_ACT_RECLASSIFY等价
#define TC_ACT_OK               0
// 提示内核丢弃封包，在ingress方向，网络栈上层无法看到封包；在egress方向，封包不会被发出
#define TC_ACT_SHOT             2
// 从tc BPF程序角度，TC_ACT_STOLEN、TC_ACT_QUEUED、TC_ACT_TRAP等价
// 类似于TC_ACT_SHOT，区别：
//   TC_ACT_SHOT导致内核通过kfree_skb()释放封包并返回NET_XMIT_DROP作为即时的反馈
//   TC_ACT_STOLEN导致内核通过consume_skb()释放封包，并且返回NET_XMIT_SUCCESS，
//      效果是上层以为封包是成功发送的
#define TC_ACT_STOLEN           4
// 利用助手函数bpf_redirect()，重定向封包到相同/不同设备的ingress/egress路径
#define TC_ACT_REDIRECT         7 

对于容器来说，容器网络命名空间和初始网络命名空间通过一对veth连接。我们可以在宿主机端实现网络策略：

1. 主机侧的egress，对应容器的ingress
2. 主机侧的ingress，对应容器的egress

将tc BPF程序挂钩到宿主机veth的egress/ingress钩子即可。

对于veth这样的虚拟设备，XDP是不适合的。因为内核在虚拟设备这里，单纯在一个skb上操作，XDP由于一些限制，无法和克隆的skb一起工作。克隆skb在内核TCP/IP栈被大量使用，用来存放重传的数据段，这里XDP钩子会被直接跳过。此外，XDP需要线性化（放到单个页）整个skb，这也导致严重的性能影响。

容器工作负载的东西向流量是主要的目标场景。

不像XDP仅作用在ingress上，tc BPF可以在某些场景下，应用到容器egress方向。在对容器透明的前提下，可以利用BPF在egress进行NAT和LB处理，利用bpf_redirection助手函数，BPF可以将封包转到任何接口的ingress/egress路径，不需要网桥之类的设备辅助。

类似XDP，流采样和监控可以通过高性能、无锁的per-CPU内存映射的perf ring buffer实现，依此tc BPF程序可以调用助手函数

bpf_skb_event_output()

由于tc BPF程序可以同时挂到ingress/egress，因此可以为任何节点实现双向的监控。

BPF程序可以预先做一些聚合，而不是把所有东西推送到用户空间。

如上文所提到，sch_clsact的egress钩子，即

sch_handle_egress()

本节介绍如何创建完整的BPF开发环境。尽管手工构建iproute2和Linux内核是非必须的（主流发行版已经内置），但是测试最新特性、或者需要贡献BPF补丁到内核、iproute2时则需要。

安装构建需要的软件：

sudo apt-get install -y make gcc libssl-dev bc libelf-dev libcap-dev \
  clang gcc-multilib llvm libncurses5-dev git pkg-config libmnl-dev bison flex \
  graphviz

BPF相关的新特性在内核的net-next分支上开发，最后的BPF fixes则在net分支上。

注意打开以下内核配置项：

CONFIG_CGROUP_BPF=y
CONFIG_BPF=y
CONFIG_BPF_SYSCALL=y
CONFIG_NET_SCH_INGRESS=m
CONFIG_NET_CLS_BPF=m
CONFIG_NET_CLS_ACT=y
# 如果目标体系结构支持JIT，自动y
CONFIG_BPF_JIT=y
CONFIG_LWTUNNEL_BPF=y
CONFIG_HAVE_EBPF_JIT=y
CONFIG_BPF_EVENTS=y
CONFIG_TEST_BPF=m

从新编译的内核启动后，运行BPF自我测试套件，应该全部通过：

cd tools/testing/selftests/bpf/
make
sudo ./test_verifier

iproute2具有独立的Git仓库：

git clone https://git.kernel.org/pub/scm/network/iproute2/iproute2.git

master分支对应内核的net分支，net-next分支对应内核的net-next分支。

执行下面的命令编译：

cd iproute2/
./configure --prefix=/usr
# 确保输出：
# ELF support: yes
# 这样iproute2才能处理LLVM BPF后端产生的ELF文件
sudo make install

bpftools是BPF程序、Map的调试、introspection工具。它位于内核源码树的tools/bpf/bpftool/

cd tools/bpf/bpftool/
make
sudo make install

LLVM 3.7+是当前唯一提供BPF后端的编译套件，GCC目前不支持。主流发行版默认启用了LLVM的BPF后端支持，因此直接安装clang和llvm包足够将C编译为BPF Object文件。

通过下面的命令确认你的LLVM支持BPF目标：

llc --version
LLVM (http://llvm.org/):
  LLVM version 10.0.0
  
  Optimized build.
  Default target: x86_64-pc-linux-gnu
  Host CPU: skylake

  Registered Targets:
    ...
    # 默认情况下，bpf目标使用编译它的CPU的端序
    bpf        - BPF (host endian)
    # 这两个目标用于交叉编译
    bpfeb      - BPF (big endian)
    bpfel      - BPF (little endian)

对于下面这个最简单的XDP Drop程序：

#include <linux/bpf.h>

#ifndef __section
# define __section(NAME)                  \
   __attribute__((section(NAME), used))
#endif

__section("prog")
int xdp_drop(struct xdp_md *ctx)
{
    return XDP_DROP;
}

char __license[] __section("license") = "GPL";

可以这样编译：

clang -O2 -Wall -target bpf -c xdp-example.c -o xdp-example.o
# 加载，需要4.12或更高版本
# ip link set dev em1 xdp obj xdp-example.o

所谓CO-RE是指一次编译，到处运行（Compile Once – Run Everywhere）。

编写可移植性（能够跨越不同内核版本运行）的BPF程序是一项挑战，BPF CO-RE能够辅助这一过程。

BPF程序本质上是一段直接插入内核的代码，它可以访问（被允许访问的）所有内核内部状态。BPF程序无法控制所运行内核的内存布局：

1. 不同内核版本，结构体字段的顺序可能不同，某些字段可能在新版本被内嵌到子结构中，字段的类型可能出现不兼容的变更
2. 根据内核构建时的配置不同，某些字段可能被注释掉

并不是所有BPF程序都需要访问内核数据结构，例如opensnoop，它依赖 kprobes/tracepoints 来追踪程序打开了那些文件，仅仅需要捕获一些系统调用参数，而系统调用提供稳定的ABI，不会随着内核版本而变化。

不幸的是，opensnoop这样的程序是少数派，不访问内核数据结构也限制了程序的能力。

内核中的BPF机制提供了一个有限集合的稳定接口，BPF程序可以依赖这套结构，不用担心跨内核的兼容性问题。尽管底层结构会发生变化，但是BPF提供的抽象保持稳定。这种接口的一个例子是

__sk_buff

sk_buff

一旦有了读取内核内部原始状态的需求，例如读取

struct task_struct

解决可移植性问题的一个方案是BCC，使用BCC时，BPF内核程序的C源码作为字符串嵌入在你的用户空间程序（控制程序）中，当控制程序被部署到目标环境后，BCC会调用内嵌的Clang/LLVM，拉取本地内核头文件，执行即席的BPF程序构建。如果字段可能在某些环境下compiled-out，你只需要在源码中使用相应的#ifdef/#else。BCC方案有一些关键的缺点：

1. Clang/LLVM组合非常大，你需要将其部署到所有运行BPF程序的机器
2. Clang/LLVM在编译时很消耗资源，如果在程序启动时编译BPF代码，可能会生产环境的工作负载产生不利影响
3. 目标机器上可能不包含匹配的内核头文件
4. 开发和测试的迭代变得痛苦，可能在运行时得到很多编译错误
5. 太多的magic，难以定位错误，你需要记住命名约定、自动为tracepoint生成的结构、依赖代码重写来读取内核数据/获取kprobe参数
6. 读写BPF Map时需要编写半面向对象的C代码，和内核中发生的不完全匹配
7. 仍然需要在用户空间编写大量的样板代码

BPF CO-RE将软件栈所有层次 —— 内核、用户空间BPF loader库（libbpf）、编译器（Clang）——的必要功能/数据片段整合到一起，来降低编写可移植性BPF程序的难度。CO-RE需要下列组件的谨慎集成和协作：

1. BTF类型信息：允许捕获关于内核、BPF程序的类型/代码的关键信息
2. Clang为BPF程序C代码提供了express the intent和记录relocation信息的手段
3. BPF loader（libbpf）根据内核的BTF和BPF程序，调整编译后的BPF代码，使其适合在目标内核上运行
4. 对于BPF CO-RE不可知的内核，提供了一些高级的BPF特性，满足高级场景

即BPF Type Format，类似于DWARF调试信息，但是没有那么generic和verbose。它是一种空间高效的、紧凑的、有足够表达能力的格式，足以描述C程序的所有类型信息。由于它的简单性和BPF去重算法，对比DWARF，BTF能够缩小100x的尺寸。现在，在运行时总是保留BTF信息是常见做法，它对应内核选项

CONFIG_DEBUG_INFO_BTF=y

BTF能够用来增强BPF verifier的能力，能够允许BPF代码直接访问内核内存，不需要

bpf_probe_read()

对于CO-RE来说，更重要的是，内核通过

/sys/kernel/btf/vmlinux

bpftool btf dump file /sys/kernel/btf/vmlinux format c

此文件通常命名为

vmlinux.h

为了启用CO-RE，并且让BPF loader（libbpf）来为正在运行的（目标）内核调整BPF程序，Clang被扩展，增加了一些built-ins。

这些built-ins会发出（emit）BTF relocations，BTF relocations是BPF程序需要读取什么信息的高层描述。假设程序需要访问task_struct->pid，Clang会将其记录：需要访问pid_t类型的、名为pid、位于task_struct结构中的字段。这样，即使字段顺序调整，甚至pid字段被放入一个内嵌的匿名结构体/联合体中，BPF程序仍然能够正确访问到pid字段。

能够捕获（进而重定位）的信息不单单是字段偏移量，还包括字段是否存在、字段的size。甚至对于位域（bitfield）字段，也能够捕获足够多的信息，让对它的访问能够被重定位。

BPF loader在加载程序时，会利用前述的（构建机的）内核BTF信息、Clang重定位信息，并读取当前内核的BTF信息，对BPF程序（ELF object文件）进行裁减（custom tailored） —— 解析和匹配所有类型、字段，更新字段偏移量，以及其它可重定位数据 —— 确保程序在当前内核上能够正确运行。

要支持CO-RE，内核不需要更多的改变（除了开启CONFIG_DEBUG_INFO_BTF）。被BPF loader（libbpf）处理过的BPF程序，对于内核来说，和在本机编译的BPF程序是完全等价的。

截至2021年，BPF CO-RE是很成熟的技术，在大量生产环境下运行。

由于引入了BPF CO-RE，超过25个BCC工具被转换为libbpf +BPF CO-RE方式编写。由于越来越多的Linux发行版（Ubuntu 20.10、RHEL 8.2+）默认开启BTF，BPF CO-RE相关工具的适用面变得越来越广，可以替代笨重的、基于python的BCC工具。

BPF CO-RE在不同BPF应用领域被广泛接受，包括追踪、性能监控、安全/审计，甚至网络BPF程序。

要使用BPF CO-RE，可以考虑从脚手架项目libbpf-bootstrap开始。

为了避免依赖于系统头文件，可以生成包含所有内核类型的vmlinux.h：

bpftool btf dump file /sys/kernel/btf/vmlinux format c > vmlinux.h

这样你的代码中就不需要包含各种内核头文件、也不必须安装kernel-devel包了：

#include <linux/sched.h>
#include <linux/fs.h>

由于BTF（以及DWARF）不会记录宏信息，因此某些常用的宏可能没有包含在vmlinux.h中，好在其中大部分可以通过bpf_helpers.h访问。

使用BCC时，你可以直接访问：

pid_t pid = task->pid;

BCC会自动将其重写为对

bpf_probe_read()

使用CO-RE的时候，由于没有BCC这种代码重写机制，为了打到同样效果，你可能需要：

1. libbpf + BPF_PROG_TYPE_TRACING：如果编写的是这类程序，你可以直接写：
   

   pid_t pid = task->pid;

   而不需要bpf_probe_read()调用。要实现可移植性，则需要将上述代码包围到

   __builtin_preserve_access_index

   中：

   pid_t pid = __builtin_preserve_access_index(({ task->pid; }));

2. 对于其它类型BPF程序，你不能直接访问结构字段，而需要：
   

   pid_t pid; bpf_probe_read(&pid, sizeof(pid), &task->pid);

   要实现可移植性，则需要：

   pid_t pid; bpf_core_read(&pid, sizeof(pid), &task->pid);
   // 或者
   bpf_probe_read(&pid, sizeof(pid), __builtin_preserve_access_index(&task->pid));

进行pointer chasing时，使用bpf_probe_read()/bpf_core_read()会变得痛苦：

u64 inode = task->mm->exe_file->f_inode->i_ino;

你需要逐步的分配指针临时变量，逐步读取字段，非常麻烦。 幸运的是，CO-RE提供了助手宏：

u64 inode = BPF_CORE_READ(task, mm, exe_file, f_inode, i_ino);

// 或者
u64 inode;
BPF_CORE_READ_INTO(&inode, task, mm, exe_file, f_inode, i_ino);

类似的，和

bpf_probe_read_str()

bpf_core_read_str()

BPF_CORE_READ_STR_INTO()

要检查字段是否在目标内核存在，可以使用

bpf_core_field_exists()

pid_t pid = bpf_core_field_exists(task->pid) ? BPF_CORE_READ(task, pid) : -1;

某些内部的、非UAPI的内核枚举值，可能跨内核版本时发生变动，甚至依赖于特定的内核配置（例如cgroup_subsys_id），这导致硬编码任何值都是不可靠的。使用Enum relocation宏

bpf_core_enum_value_exists()

bpf_core_enum_value()

要捕获（如果不确定某个字段是否在别的内核版本中发生了类型变更）字段的size，可以使用

bpf_core_field_size()

u32 comm_sz = bpf_core_field_size(task->comm);

位域字段的读取，可以使用：

struct tcp_sock *s = ...;

// 读取s->is_cwnd_limited对应的位域字段
bool is_cwnd_limited = BPF_CORE_READ_BITFIELD(s, is_cwnd_limited);

// 或者
u64 is_cwnd_limited;
BPF_CORE_READ_BITFIELD_PROBED(s, is_cwnd_limited, &is_cwnd_limited);

某些情况下，内核之间不是简单的结构性差异：

1. 同一含义的字段可能被重命名
2. 字段的含义可能改变，例如从4.6开始，task_struct.utime/stime从原先的以jiffies为单位改为纳秒为单位

内核配置的差异，可能会出现某些内核下无法读取字段的情况。

CO-RE提供处理这些问题的辅助机制是libbpf提供的extern Kconfig variables和struct flavors。

BPF程序可以定义具有知名名称的变量，例如LINUX_KERNEL_VERSION；或者一个匹配内核Kconfig键的变量，例如CONFIG_HZ。libbpf能够自动设置这些外部变量为匹配当前内核的值，BPF verifier也会跟踪这些变量，并进行高级的流分析和dead code消除。

//                              声明外部Kconfig变量
extern u32 LINUX_KERNEL_VERSION __kconfig;
extern u32 CONFIG_HZ __kconfig;

u64 utime_ns;

if (LINUX_KERNEL_VERSION >= KERNEL_VERSION(4, 11, 0))
    utime_ns = BPF_CORE_READ(task, utime);
else
    /* convert jiffies to nanoseconds */
    utime_ns = BPF_CORE_READ(task, utime) * (1000000000UL / CONFIG_HZ);

struct flavors则用于解决内核存在不兼容类型的情况。实际上就是为不同版本的内核定义不同的结构：

// 新版本内核使用此结构
struct thread_struct {
    ...
    u64 fsbase;
    ...
};

// 4.6或者更低版本使用此结构
// 三下划线及其后面的部分，被认为是结构的一个flavor，flavor部分会被libbpf忽略，
// 这意味着在进行relocation时thread_struct___v46仍然对应着运行中的内核的thread_struct结构

struct thread_struct___v46 { /* ___v46 is a "flavor" part */
    ...
    u64 fs;
    ...
};

extern int LINUX_KERNEL_VERSION __kconfig;
...

struct thread_struct *thr = ...;
u64 fsbase;
if (LINUX_KERNEL_VERSION > KERNEL_VERSION(4, 6, 0))
    // 强制转型为flavor，从而抽取需要的字段
    fsbase = BPF_CORE_READ((struct thread_struct___v46 *)thr, fs);
else
    fsbase = BPF_CORE_READ(thr, fsbase);

如果没有struct flavors，你就不能编写可移植的BPF程序。你只能通过#ifdef条件编译为多个BPF object文件，然后在控制程序中，判断当前内核版本，然后选择加载匹配的BPF object。

即使知道目标内核版本、配置，BPF程序可能仍然不知道如何从内核中读取需要的数据。这种情况下，可以通过用户空间的控制程序进行精确的判断，然后通过BPF Map传递一个配置信息给BPF程序，BPF程序根据此配置信息改变自己的行为。这种做法的缺点是：

1. BPF程序每次都需要读取Map的成本，对于高性能BPF程序不可忽略
2. 配置信息即使在BPF程序启动后是不可变的（没有代码去改它），但是对于BPF verifier来说，仍然是一个黑盒。BPF verifier不能根据配置信息来裁减掉dead code，或者进行其它高级的代码分析。这样，为新版本内核（假设这个版本引入了新的助手函数）编写的分支，在旧版本内核上无法被裁减，从而可能破坏程序（无法通过校验，以为助手函数不存在）

解决上述缺点的方法是使用只读全局变量。变量的值由控制程序加载BPF object文件后设置（修改ELF文件）。这不会带来Map查询的成本，BPF verifer会将其此变量作为常量看待，从而裁减dead code。

/* global read-only variables, set up by control app */
const bool use_fancy_helper;
const u32 fallback_value;

...

u32 value;
if (use_fancy_helper)
    value = bpf_fancy_helper(ctx);
else
    value = bpf_default_helper(ctx) * fallback_value;

通过BPF skeleton，可以很容易的从用户空间修改ELF文件。

利用上文提到的BPF CO-RE提供的多种能力，编写好代码后，你需要用Clang 10+版本，编译得到BPF object文件。

从编译好的BPF object文件，可以利用

bpftool gen skeleton

将BPF skeleton（头文件）包含到你的用户空间控制程序中，获得打开、加载、挂钩BPF程序，以及修改BPF对象等能力。

使用C语言编写eBPF程序，需要注意：

1. 可以访问助手函数、上下文对象
2. 程序的入口点通过段来指定，而非main函数
3. 在对象文件中包含多个入口点是允许的
4. 所有库函数调用被内联，因而运行时不存在函数调用的开销
5. 没有全局变量（5.5-）
6. 没有循环
7. 没有常量
8. LLVM的内置函数一般是可用的、并且被内联
9. 栈空间大小限制为512字节

除非使用支持BPF-BPF调用的4.16+内核（和LLVM6.0+），所有函数都需要被内联，没有函数调用（老版本LLVM上）或共享库调用。

BPF程序不能使用共享库，公共代码可以放在头文件中，被主程序include。尽管不能使用共享库，但是通过include头文件来使用静态内联函数、宏定义是很常见的。

为了确保这一点，需要为所有作为库使用的函数标注__inline：

#include <linux/bpf.h>

#ifndef __section
# define __section(NAME)                  \
   __attribute__((section(NAME), used))
#endif

#ifndef __inline
# define __inline                         \
   // 使用always_inline，因为仅仅使用inline编译器仍然可能在
   // 代码过大的情况下不内联，从而导致在ELF文件中生成一个relocation entry
   // iproute2这样的ELF loader不能解析BPF程序
   // 仅仅BPF Map是ELF loader能够处理的relication entry
   inline __attribute__((always_inline))
#endif

static __inline int foo(void)
{
    return XDP_DROP;
}

__section("prog")
int xdp_drop(struct xdp_md *ctx)
{
    return foo();
}

char __license[] __section("license") = "GPL";

从4.16开始支持在BPF程序中使用BPF-BPF函数调用，libbpf v0.2+也对此特性提供的完整的支持，确保代码的relocations/adjustment正确进行。你可以去掉

__always_inline

__noinline

非内联的global函数从5.5+开始被支持，但是和static函数比起来具有不同的语义以及校验约束。

BPF的C程序依赖段（section）注解。典型的C程序被结构化为三个或更多的段，BPF ELF loader通过段的名字来抽取、准备相关的信息，以便载入程序和Map。

例如，iproute2使用maps和license作为默认的段名称，来获取创建Map所需元数据，以及BPF程序的License信息。加载时，License信息也被推入内核，这样某些仅仅在GPL协议下暴露的函数（例如bpf_ktime_get_ns和bpf_probe_read）允许被调用，确保BPF程序的License兼容性。

其它的段名，都专用于BPF程序代码。下面的代码使用了ingress/egress两个段，可以被tc加载并挂钩到网络设备的ingress/egress钩子：

#include <linux/bpf.h>
#include <linux/pkt_cls.h>
#include <stdint.h>
#include <iproute2/bpf_elf.h>

#ifndef __section
# define __section(NAME)                  \
   __attribute__((section(NAME), used))
#endif

#ifndef __inline
# define __inline                         \
   inline __attribute__((always_inline))
#endif

// 共享的Map是全局变量，因此访问它的时候需要同步
#ifndef lock_xadd
# define lock_xadd(ptr, val)              \
   ((void)__sync_fetch_and_add(ptr, val))
#endif

// 这个宏用于将BPF助手函数映射到C代码
// 函数map_lookup_elem被映射到定义uapi/linux/bpf.h在中的枚举值 BPF_FUNC_map_lookup_elem
// 在载入内核后，Verifier会检查传入的参数是否为期望的类型，并且将对助手函数的调用指向真实函数的调用
#ifndef BPF_FUNC
# define BPF_FUNC(NAME, ...)              \
   (*NAME)(__VA_ARGS__) = (void *)BPF_FUNC_##NAME
#endif

static void *BPF_FUNC(map_lookup_elem, void *map, const void *key);
// static void (*map_lookup_elem)(void *map, const void *key) = (void *)BPF_FUNC_map_lookup_elem;




// 这个是共享的Map，类型struct bpf_elf_map是iproute2定义的
// iproute2提供了公共的BPF ELF loader，因此struct bpf_elf_map对于XDP和tc程序来说是一样的
//                         必须放在maps段，这样loader才能发现
//                         可以定义多个Map，都必须放在maps段
struct bpf_elf_map acc_map __section("maps") = {
    .type           = BPF_MAP_TYPE_ARRAY,
    .size_key       = sizeof(uint32_t),
    .size_value     = sizeof(uint32_t),
    // 该Map被Pin到PIN_GLOBAL_NS，这意味着Map将被tc钉为BPF伪文件系统中的位于
    // /sys/fs/bpf/tc/globals/目录下的节点。对于此acc_map，节点路径为
    // /sys/fs/bpf/tc/globals/acc_map
    // global是跨越多个Object文件的全局命名空间。如果不同BPF程序中均有名为acc_map
    // 的Map映射到PIN_GLOBAL_NS，这这些程序会共享统一Map。仅仅第一个载入的BPF程序会触发
    // Map的创建，后续载入的程序直接使用

    // 如果取值PIN_NONE则不会映射为BPF文件系统中的节点，当tc退出后，无法从用户空间访问Map
    .pinning        = PIN_GLOBAL_NS,
    .max_elem       = 2,
};

// 这个是共享的内联函数
static __inline int account_data(struct __sk_buff *skb, uint32_t dir)
{
    uint32_t *bytes;
    // 将Map传递给助手函数
    bytes = map_lookup_elem(&acc_map, &dir);
    if (bytes)
            lock_xadd(bytes, skb->len);

    return TC_ACT_OK;
}

// 两个段，都会调用account_data往Map中写入数据
__section("ingress")
int tc_ingress(struct __sk_buff *skb)
{
    return account_data(skb, 0);
}

__section("egress")
int tc_egress(struct __sk_buff *skb)
{
    return account_data(skb, 1);
}

char __license[] __section("license") = "GPL";

使用下面的命令编译：

clang -O2 -Wall -target bpf -c tc-example.c -o tc-example.o

利用tc加载该程序：

tc qdisc add dev eth0 clsact
tc filter add dev eth0 ingress bpf da obj tc-example.o sec ingress
tc filter add dev eth0 egress bpf da obj tc-example.o sec egress

tc filter show dev eth0 ingress
# filter protocol all pref 49152 bpf
# filter protocol all pref 49152 bpf handle 0x1 tc-example.o:[ingress] direct-action id 1 tag c5f7825e5dac396f

tc filter show dev em1 egress
# filter protocol all pref 49152 bpf
# filter protocol all pref 49152 bpf handle 0x1 tc-example.o:[egress] direct-action id 2 tag b2fd5adc0f262714

mount | grep bpf
# sysfs on /sys/fs/bpf type sysfs (rw,nosuid,nodev,noexec,relatime,seclabel)
# bpf on /sys/fs/bpf type bpf (rw,relatime,mode=0700)

tree /sys/fs/bpf/
# /sys/fs/bpf/
# +-- ip -> /sys/fs/bpf/tc/
# +-- tc
# |   +-- globals
# |       +-- acc_map
# +-- xdp -> /sys/fs/bpf/tc/

一旦有封包通过eth0接口，则acc_map中的计数器值就会增加。

除非内核版本在5.5+以上，BPF程序中没有普通C程序中的全局变量。5.5+的全局变量底层仍然是基于BPF Map实现的。

作为变通方案，可以使用BPF_MAP_TYPE_PERCPU_ARRAY类型的Map，这种Map为每个CPU核心存储一个任意大小的值。由于BPF程序在运行过程中绝不会被抢占，在此Map中初始化一个临时的缓冲区（例如为了突破栈的大小限制）用作全局变量是安全的。在发生尾调用的情况下也不会发生抢占，Map的内容不会消失。

对于任何需要跨越多次BPF程序运行保存的状态，都使用普通BPF Map即可。

由于一切内联、不支持全局变量，定义

const

打印调试消息可以利用助手函数trace_printk：

static void BPF_FUNC(trace_printk, const char *fmt, int fmt_size, ...);

#ifndef printk
# define printk(fmt, ...)                                      \
    ({                                                         \
        char ____fmt[] = fmt;                                  \
        trace_printk(____fmt, sizeof(____fmt), ##__VA_ARGS__); \
    })
#endif


// 调用
printk("skb len:%u\n", skb->len);

// 在用于空间使用下面的命令查看打印的消息
// tc exec bpf dbg

不建议在生产环境使用trace_printk()助手函数，因为类似于

"skb len:%u\n"

对于网络应用，可以使用

skb_event_output()

xdp_event_output()

除了助手函数之外，BPF程序不能发起任何函数调用，因此公共库代码需要实现为内联函数。此外LLVM提供的一些builtins可以被使用，并且总是保证被内联：

#ifndef memset
# define memset(dest, chr, n)   __builtin_memset((dest), (chr), (n))
#endif

#ifndef memcpy
# define memcpy(dest, src, n)   __builtin_memcpy((dest), (src), (n))
#endif

#ifndef memmove
# define memmove(dest, src, n)  __builtin_memmove((dest), (src), (n))
#endif

内置函数memcmp()存在一些边缘场景，会导致不发生inline，因此在LLVM解决此问题之前不推荐使用。

BPF Verifier会检查程序代码，确保其不包含循环，目的是确保程序总是能停止。

只有非常特殊形式的循环被允许：

// 使用该指令，内核5.3+不再需要
#pragma unroll
    // 循环的upper buounds是常量
    for (i = 0; i < IPV6_MAX_HEADERS; i++) {
        // ...
    }

另外一种比较刁钻的实现循环的方式是，自我尾调用， 使用一个BPF_MAP_TYPE_PERCPU_ARRAY作为变量存储。这种方式的循环次数是动态的，但是最多迭代34次（初始程序，加上最多33次尾调用）。

尾调用提供了一种灵活的、在运行时原子的修改程序行为的方式，它的做法是从一个BPF程序跳转到另外一个，同时保留当前栈帧。尾调用没有return的概念，当前程序直接被替换掉。

发起尾调用时必须使用BPF_MAP_TYPE_PROG_ARRAY类型的Map，传递目标BPF程序所在索引。

使用尾调用可以非常灵活的对程序进行“分区”。例如挂钩到XDP或tc的根BPF程序可以发起对索引为0的BPF程序的尾调用，后者执行流量采样，然后跳转到BPF程序1，在此应用防火墙策略。封包在此被丢弃，或进一步尾调用2来处理，BPF程序2修改封包并将其从网络接口发出。

#ifndef __stringify
# define __stringify(X)   #X
#endif

#ifndef __section
# define __section(NAME)                  \
   __attribute__((section(NAME), used))
#endif

#ifndef __section_tail
# define __section_tail(ID, KEY)          \
   __section(__stringify(ID) "/" __stringify(KEY))
#endif

#ifndef BPF_FUNC
# define BPF_FUNC(NAME, ...)              \
   (*NAME)(__VA_ARGS__) = (void *)BPF_FUNC_##NAME
#endif

#define BPF_JMP_MAP_ID   1

static void BPF_FUNC(tail_call, struct __sk_buff *skb, void *map,
                     uint32_t index);

// 创建一个eBPF程序数组并且钉到BPF文件系统的全局命名空间下的/jmp_map节点
struct bpf_elf_map jmp_map __section("maps") = {
    .type           = BPF_MAP_TYPE_PROG_ARRAY,
    .id             = BPF_JMP_MAP_ID,
    .size_key       = sizeof(uint32_t),
    .size_value     = sizeof(uint32_t),
    .pinning        = PIN_GLOBAL_NS,
    .max_elem       = 1,
};

// iproute2的BPF ELF loader能够识别标记为__section_tail()的块，将其存放到某个程序数组中
// 第一个参数ID用于决定存放到哪个数组，第二个参数用于决定存放到数组的哪个索引
// 不仅仅是tc，任何iproute2支持的BPF程序类型（XDP，lwt等）都可以使用这种标记
__section_tail(BPF_JMP_MAP_ID, 0)
int looper(struct __sk_buff *skb)
{
    printk("skb cb: %u\n", skb->cb[0]++);
    tail_call(skb, &jmp_map, 0);
    return TC_ACT_OK;
}

// 主程序
__section("prog")
int entry(struct __sk_buff *skb)
{
    skb->cb[0] = 0;
    // 发起尾调用
    tail_call(skb, &jmp_map, 0);
    return TC_ACT_OK;
}

char __license[] __section("license") = "GPL";

钉在BPF伪文件系统的BPF程序数组，可被用户空间程序查询或修改，tc也提供了更新BPF程序的命令：

#                   更换globals/jmp_map的 0索引元素
#                                             用new.o的 foo段代替
tc exec bpf graft m:globals/jmp_map key 0 obj new.o sec foo

BPF程序的栈空间仅有512字节，因此编码时需要小心。要使用一个较大的缓冲区，可以从BPF_MAP_TYPE_PERCPU_ARRAY类型的Map分配。

现代编译器默认情况下会进行字节边界对齐 —— 结构体成员被对齐到是它们长度的整数倍的内存边界，空出的部分自动补白：

struct called_info {
    u64 start;  // 8-byte
    u64 end;    // 8-byte
    u32 sector; // 4-byte
}; // size of 20-byte ?

printf("size of %d-byte\n", sizeof(struct called_info)); // size of 24-byte

// Actual compiled composition of struct called_info
// 0x0(0)                   0x8(8)
//  ↓________________________↓
//  |        start (8)       |
//  |________________________|
//  |         end  (8)       |
//  |________________________|
//  |  sector(4) |  PADDING  | <= address aligned to 8
//  |____________|___________|     with 4-byte PADDING.

由于字节对齐的原因，结构体的大小通常比期望的大。

BPF Verifier会检查栈的边界，确保程序不会越界（512字节）访问，或者访问未初始化的栈区域。使用带补白的结构作为Map的值，可能导致在

bpf_prog_load()

你需要使用pack指令移除补白：

#pragma pack(4)
struct called_info {
    u64 start;  // 8-byte
    u64 end;    // 8-byte
    u32 sector; // 4-byte
}; // size of 20-byte ?

printf("size of %d-byte\n", sizeof(struct called_info)); // size of 20-byte

// Actual compiled composition of packed struct called_info
// 0x0(0)                   0x8(8)
//  ↓________________________↓
//  |        start (8)       |
//  |________________________|
//  |         end  (8)       |
//  |________________________|
//  |  sector(4) |             <= address aligned to 4
//  |____________|                 with no PADDING.

移除字节对齐补白后，会导致CPU内存访问效率的降低，在某些体系结构下，不对齐的访问（unaligned access）可能被Verifier拒绝。

所以，最优的方式是人工添加仅用于实现字节对齐的pad字段：

struct called_info {
    u64 start;  // 8-byte
    u64 end;    // 8-byte
    u32 sector; // 4-byte
    u32 pad;    // 4-byte
}; // size of 24-byte ?

printf("size of %d-byte\n", sizeof(struct called_info)); // size of 24-byte

// Actual compiled composition of struct called_info with explicit padding
// 0x0(0)                   0x8(8)
//  ↓________________________↓
//  |        start (8)       |
//  |________________________|
//  |         end  (8)       |
//  |________________________|
//  |  sector(4) |  pad (4)  | <= address aligned to 8
//  |____________|___________|     with explicit PADDING.

诸如bpf_skb_store_bytes之类的助手函数，会导致封包的size发生变化。由于Verifier无法在运行时跟踪这种变化，因此一旦调用了这类助手函数，对数据的引用（指针）立刻会被Verifer无效化（invalidated）：

struct iphdr *ip4 = (struct iphdr *) skb->data + ETH_HLEN;

skb_store_bytes(skb, l3_off + offsetof(struct iphdr, saddr), &new_saddr, 4, 0);

// Verifier会拒绝下面的代码，因为此处ip4这个指针已经无效了，不能解引用
if (ip4->protocol == IPPROTO_TCP) {
    // do something
}

解决办法是重新获取引用：

struct iphdr *ip4 = (struct iphdr *) skb->data + ETH_HLEN;

skb_store_bytes(skb, l3_off + offsetof(struct iphdr, saddr), &new_saddr, 4, 0);

// 重新获取引用
ip4 = (struct iphdr *) skb->data + ETH_HLEN;

if (ip4->protocol == IPPROTO_TCP) {
    // do something
}

bpftool是内核提供（tools/bpf/bpftool/）的，主要的BPF内省（introspection）和调试工具。它支持：

1. Dump出当前加载到系统中的所有BPF程序，以及Maps
2. 列出指定程序使用的Maps
3. Dump中Map的所有键值对
4. 对Map键值对进行增删改查
5. 将Map或程序钉到BPF伪文件系统

指定bpftool操作的目标时，可以使用ID，或者目标在BPF伪文件系统中的路径。

列出所有程序：

bpftool prog

输出为JSON：

# 对于所有子命令，都支持输出JSON
bpftool prog --json --pretty

列出所有Map：

bpftool map

查看特定程序：

bpftool prog show id 406
#    程序类型为sched_cls，即BPF_PROG_TYPE_SCHED_CLS
406: sched_cls  tag e0362f5bd9163a0a
#    加载此程序的用户和时间
     loaded_at Apr 09/16:24  uid 0
#    指令序列长度为11144字节
#                   JIT编译后的映像为7721字节
#                               程序本身（不包含Map）占用空间122888字节
#                                                使用的Maps列表
     xlated 11144B  jited 7721B  memlock 12288B  map_ids 18,20,8,5,6,14

使用下面的命令可以dump出BPF程序的指令：

# bpftool prog dump xlated id 406
 0: (b7) r7 = 0
 1: (63) *(u32 *)(r1 +60) = r7
 2: (63) *(u32 *)(r1 +56) = r7
 3: (63) *(u32 *)(r1 +52) = r7
[...]
47: (bf) r4 = r10
48: (07) r4 += -40
49: (79) r6 = *(u64 *)(r10 -104)
50: (bf) r1 = r6
51: (18) r2 = map[id:18]                    # <-- 使用ID为18的Map
53: (b7) r5 = 32
54: (85) call bpf_skb_event_output#5656112  # <-- 调用助手函数
55: (69) r1 = *(u16 *)(r6 +192)
[...]

使用下面的命令可以dump出程序JIT后的汇编指令：

# bpftool prog dump jited id 406
 0:        push   %rbp
 1:        mov    %rsp,%rbp
 4:        sub    $0x228,%rsp
 b:        sub    $0x28,%rbp
 f:        mov    %rbx,0x0(%rbp)
13:        mov    %r13,0x8(%rbp)
17:        mov    %r14,0x10(%rbp)
1b:        mov    %r15,0x18(%rbp)
1f:        xor    %eax,%eax
21:        mov    %rax,0x20(%rbp)
25:        mov    0x80(%rdi),%r9d

Dump整个Map：

bpftool map dump id 5

libbpf是一个C/C++库，作为内核的一部分进行维护，位于tools/lib/bpf目录下。内核自带的eBPF代码样例均依赖于此库。libbpf提供了一个eBPF loader，用于处理LLVM生成的ELF文件，将其载入内核。libbpf中的一部分特性源自BCC，它也包含了一些额外的功能，例如全局变量、BPF Skeletons。

为了支持eBPF相关操作，例如载入eBPF程序、挂钩到特定事件、创建和访问eBPF Map，Linux中引入了一个新的系统调用

bpf

该系统调用的签名如下：

//      命令      用于内核和用户空间的数据交互  attr的字节数
int bpf(int cmd, union bpf_attr *attr,      unsigned int size);
// cmd有很多，要么和eBPF程序交互、要么和eBPF Map交互，或者同时和两者交互

该命令用于载入eBPF程序。载入的时候需要指明程序的类型。程序类型决定了以下事项：

1. 程序在何处挂钩
2. 校验器允许程序调用哪些助手函数
3. 是否允许直接访问网络封包数据
4. 传递给程序的第一个参数的对象的类型

可以看到，程序类型规定了eBPF程序的API接口。某些时候，定义一个新的程序类型，仅仅是为了限制可调用函数的列表，例如BPF_PROG_TYPE_CGROUP_SKB、BPF_PROG_TYPE_SOCKET_FILTER

用于创建eBPF Maps，参考下文。

网络封包过滤器

挂钩到一个KProbe，BPF程序在某个内核函数被调用时触发

网络流量控制（TC）的分类器（classifier）

网络流量控制（TC）动作（action）

挂钩到一个Tracepoint，当执行到内核特定的代码路径时触发BPF程序

在设备驱动接收路径上运行的网络封包过滤器

决定是否应当触发一个Perf Event Handler

为控制组提供的网络封包过滤器

同上，但是允许修改套接字选项

用于轻量级隧道（lightweight tunnels ）的网络封包过滤器

用于设置套接字选项

用于在套接字之间转发封包

决定是否允许一个设备操作

部分Map专供特定的助手函数使用，以实现特殊任务。

要在BPF程序中定义一个Map，需要用到如下结构：

struct bpf_map_def {
        unsigned int type; // Map类型
        unsigned int key_size; // 键的长度
        unsigned int value_size; // 值的长度
        unsigned int max_entries; // 最大键值对数量
        unsigned int map_flags; // 标记
        unsigned int inner_map_idx;
        unsigned int numa_node;
};

下面是一个例子：

struct bpf_map_def SEC("maps") my_map = {
        .type = BPF_MAP_TYPE_ARRAY,
        .key_size = sizeof(int),
        .value_size = sizeof(u64),
        .max_entries = MAX_CPU,
};

在加载阶段，

bpf_load.c

bpf_create_map_node()

bpf_create_map_in_map_node()

bpf

BPF_MAP_CREATE

除非你在编写lwt或tc等类型的BPF程序，你都应该使用上面的方式来定义Map。tc之类的程序使用iproute2作为loader，可以使用下面的结构来定义Map：

#define PIN_GLOBAL_NS           2

struct bpf_elf_map {
        __u32 type;
        __u32 size_key;
        __u32 size_value;
        __u32 max_elem;
        __u32 flags;
        __u32 id;
        __u32 pinning;
};    

struct bpf_elf_map SEC("maps") tun_iface = {
        .type = BPF_MAP_TYPE_ARRAY,
        .size_key = sizeof(int),
        .size_value = sizeof(int),
        .pinning = PIN_GLOBAL_NS,
        .max_elem = 1,

};

所谓Pinning是指通过文件系统路径来暴露Map。对于tc之类的iproute2加载的程序，可以使用这些宏：

#define PIN_NONE        0
#define PIN_OBJECT_NS        1
// 钉到/sys/fs/bpf/tc/globals/ 
#define PIN_GLOBAL_NS        2

其它程序，你可以手工调用libbpf钉住Map：

bpf_obj_pin(fd, path)

mapfd = bpf_obj_get(pinned_file_path);

检查头文件

linux/bpf_types.h

bpf_map_ops

BPF_MAP_TYPE(BPF_MAP_TYPE_ARRAY, array_map_ops)
BPF_MAP_TYPE(BPF_MAP_TYPE_PERCPU_ARRAY, percpu_array_map_ops)

不过对于BPF开发者来说，所有Map都可以在eBPF或用户空间程序中，通过

bpf_map_lookup_elem()

bpf_map_update_elem()

所有的Map类型定义在枚举

bpf_map_type

哈希表。

Array Map，为快速查找优化。

键是数组索引值（4字节，64bit），不支持删除键值。所有其它Array Map都具有此特征。

存放对应eBPF程序的文件描述符的数组。用于实现

bpf_tail_call()

per-CPU Array Map，也就是每个CPU对应一个值。键仍然是数字，值则是和CPU个数相同的数组：

long values[nr_cpus];
ret = bpf_map_lookup_elem(map_fd, &next_key, values);
if (ret) {
    perror("Error looking up stat");
    continue;
}
for (i = 0; i < nr_cpus; i++) {
    sum += values[i];
} 

此Map可用于代替栈上变量，分配大的缓冲区，以解决栈空间仅512字节的问题。亦可用作全局变量，以解决较旧版本内核中BPF程序没有原生全局变量支持的问题

由于值是per-CPU的，而执行中的BPF程序不会被抢占。因此只要正确编码（仅访问当前CPU的值），就不会产生竞态条件。对于会被频繁执行的代码路径，一般会考虑per-CPU的Map。

即perfbuf，per-CPU的缓冲区。在内核空间，供

bpf_perf_event_output()

在用户空间，可以进行epoll，当有数据输出时会得到通知。

即ringbuf，perfbuf的继任，所有CPU共享的一个环形缓冲区。

在用户空间，存放cgroup的文件描述符。

在内核空间，调用

bpf_skb_under_cgroup()

per-CPU的哈希表

使用LRU算法的哈希表

per-CPU的使用LRU算法的哈希表

最长前缀匹配的字典树（trie），可用于IP地址范围匹配。

存储栈追踪信息。

Map的数组。

Map的Map。

存储和查找网络设备引用。

存储和查找套接字，允许基于助手函数，实现套接字重定向。

助手函数由libbpf库提供，定义在

bpf_helpers.h

签名：

void *bpf_map_lookup_elem(struct bpf_map *map, const void *key)

查找eBPF中和一个Key关联的条目。如果找不到条目，返回NULL

签名：

int bpf_map_update_elem(struct bpf_map *map, const void *key, const void *value, u64 flags)

添加或修改一个Key关联的值。flags可以是以下之一：

1. BPF_NOEXIST 键值必须不存在，即执行添加操作。不能和BPF_MAP_TYPE_ARRAY、BPF_MAP_TYPE_PERCPU_ARRAY联用
2. BPF_EXIST，键值必须存在，即执行更新操作
3. BPF_ANY，更新或修改

签名：

int bpf_map_delete_elem(struct bpf_map *map, const void *key)

从eBPF Map中删除条目

签名：

int bpf_probe_read(void *dst, u32 size, const void *src)

对于Tracing用途的eBPF程序，可以安全的从src读取size字节存储到dst

签名：

u64 bpf_ktime_get_ns(void)

读取系统从启动到现在的纳秒数，返回ktime

签名：

int bpf_trace_printk(const char *fmt, u32 fmt_size, ...)

类似于printk()的调试工具，从DebugFS打印由fmt所定义的格式化字符串到

/sys/kernel/debug/tracing/trace

每当此函数被调用，它都会打印一行到trace，格式取决于配置

/sys/kernel/debug/tracing/trace_options

# 当前任务的名字
#      当前任务的PID
#            当前CPU序号
#                  每个字符表示一个选项
#                       时间戳
#                                      BPF使用的指令寄存器的Fake值
telnet-470   [001] .N.. 419421.045894: 0x00000001: <formatted msg>

可以使用的格式化占位符：

%d, %i, %u, %x, %ld, %li, %lu, %lx, %lld, %lli, %llu, %llx, %p, %s

该函数比较缓慢，应该仅用于调试目的。

签名：

u32 bpf_get_prandom_u32(void)

获得一个伪随机数。

签名：

u32 bpf_get_smp_processor_id(void)

得到SMP处理器ID，需要注意，所有eBPF都在禁止抢占的情况下运行，这意味着在eBPF程序的执行过程中，此ID不会改变。

签名：

int bpf_skb_store_bytes(struct sk_buff *skb, u32 offset, const void *from, u32 len, u64 flags)

存储缓冲区from的len字节到，skb所关联的封包的offset位置。flags是以下位域的组合：

1. BPF_F_RECOMPUTE_CSUM：自动重新计算修改后的封包的Checksum
2. BPF_F_INVALIDATE_HASH：重置

   skb->hash

   skb->swhash

   skb->l4hash

   为0

调用此助手函数会导致封包缓冲区改变，因此在加载期间校验器对指针的校验将失效，必须重新校验。

签名：

int bpf_skb_load_bytes(const struct sk_buff *skb, u32 offset, void *to, u32 len)

从skb中的offset位置读取len长的数据，存放到to缓冲区。

从4.7开始，该函数的功能基本被直接封包访问（direct packet access）代替 ——

skb->data

skb->data_end

签名：

int bpf_l3_csum_replace(struct sk_buff *skb, u32 offset, u64 from, u64 to, u64 size)

重新计算L3（IP）的Checksum。计算是增量进行的，因此助手函数必须知道被修改的头字段的前值（from）、修改后的值（to），以及被修改字段的字节数（size，2或4）。你亦可将from和size设置为0，并将字段修改前后的差存放到to。offset用于指示封包的IP Checksum的位置

调用此助手函数会导致封包缓冲区改变，因此在加载期间校验器对指针的校验将失效，必须重新校验。

签名：

int bpf_l4_csum_replace(struct sk_buff *skb, u32 offset, u64 from, u64 to, u64 flags)

重新计算L4（TCP/UDP/ICMP）的Checksum。计算是增量进行的，因此助手函数必须知道被修改的头字段的前值（from）、修改后的值（to），以及被修改字段的字节数（存放在flags的低4bit，2或4）。你亦可将from和flags低4bit设置为0，并将字段修改前后的差存放到to。offset用于指示封包的IP Checksum的位置。

flags的高位用于存放以下标记：

1. BPF_F_MARK_MANGLED_0，如果Checksum是null，则不去修改它，除非设置了BPF_F_MARK_ENFORCE
2. CSUM_MANGLED_0，对于导致Checksum为null的更新操作，设置此标记
3. BPF_F_PSEUDO_HDR，提示使用pseudo-header来计算Checksum

调用此助手函数会导致封包缓冲区改变，因此在加载期间校验器对指针的校验将失效，必须重新校验。

签名：

int bpf_tail_call(void *ctx, struct bpf_map *prog_array_map, u32 index)

这是一个特殊的助手函数，用于触发尾调用 —— 跳转到另外一个eBPF程序。新程序将使用一样的栈帧，但是被调用者不能访问调用者在栈上存储的值，以及寄存器。

使用场景包括：

1. 突破eBPF程序长度限制
2. 在不同条件下进行跳转（到子程序）

出于安全原因，可以连续执行的尾调用次数是受限制的。限制定义在内核宏MAX_TAIL_CALL_CNT中，默认32，无法被用户空间访问

当调用发生后，程序尝试跳转到prog_array_map（BPF_MAP_TYPE_PROG_ARRAY类型的Map）的index索引处的eBPF程序，并且将当前ctx传递给它。

如果调用成功，则当前程序被替换掉，不存在函数调用返回。如果调用失败，则不产生任何作用，当前程序继续运行后续指令。失败的原因包括：

1. 指定的index不存在eBPF程序
2. 当前尾调用链的长度超过限制

签名：

int bpf_clone_redirect(struct sk_buff *skb, u32 ifindex, u64 flags)

克隆skb关联的封包，并且重定向到由ifindx所指向的网络设备。入站/出站路径都可以用于重定向。标记BPF_F_INGRESS用于确定是重定向到入站（ingress）还是出站（egress）路径，如果该标记存在则入站。

调用此助手函数会导致封包缓冲区改变，因此在加载期间校验器对指针的校验将失效，必须重新校验。

签名：

int bpf_redirect(u32 ifindex, u64 flags)

重定向封包到ifindex所指向的网络设备。类似于bpf_clone_redirect，但是不会进行封包克隆，因而性能较好。缺点是，redirect操作实际上是在eBPF程序返回后的某个代码路径上发生的。

除了XDP之外，入站/出站路径都可以用于重定向。标记BPF_F_INGRESS用于指定是ingress还是egress。当前XDP仅仅支持重定向到egress接口，不支持设置flag

对于XDP，成功返回XDP_REDIRECT，出错返回XDP_ABORTED。对于其它eBPF程序，成功返回TC_ACT_REDIRECT，出错返回TC_ACT_SHOT

签名：

int bpf_redirect_map(struct bpf_map *map, u32 key, u64 flags)

将封包重定向到map的key键指向的endpoint。根据map的类型，它的值可能指向：

1. 网络设备，用于转发封包到其它ports
2. CPU，用于重定向XDP帧给其它CPU，仅仅支持Native（驱动层支持的） XDP

flags必须置零。

当重定向给网络设备时，该函数比bpf_redirect性能更好。这是由一系列底层实现细节之一决定的，其中之一是该函数会以bulk方式将封包发送给设备。

如果成功返回XDP_REDIRECT，否则返回XDP_ABORTED。

签名：

int bpf_sk_redirect_map(struct bpf_map *map, u32 key, u64 flags)

将封包重定向给map（类型BPF_MAP_TYPE_SOCKMAP）的key所指向的套接字。ingress/egress接口都可以用于重定向。标记BPF_F_INGRESS用于确定是不是ingress。

如果成功返回SK_PASS，否则返回SK_DROP。

签名：

int bpf_sock_map_update(struct bpf_sock_ops *skops, struct bpf_map *map, void *key, u64 flags)

添加/更新map的条目，skopts作为key的新值。flags是以下其中之一：

1. BPF_NOEXIST，仅添加
2. BPF_EXIST，仅更新
3. BPF_ANY，添加或更新

签名：

int bpf_skb_vlan_push(struct sk_buff *skb, __be16 vlan_proto, u16 vlan_tci)

将vlan_proto协议的vlan_tci（VLAN Tag控制信息）Push给skb关联的封包，并且更新Checksum。需要注意ETH_P_8021Q和ETH_P_8021AD的vlan_proto是不一样的，这里使用前者。

调用此助手函数会导致封包缓冲区改变，因此在加载期间校验器对指针的校验将失效，必须重新校验。

签名：

int bpf_skb_vlan_pop(struct sk_buff *skb)

弹出skb关联的封包的VLAN头。

调用此助手函数会导致封包缓冲区改变，因此在加载期间校验器对指针的校验将失效，必须重新校验。

签名：

int bpf_skb_get_tunnel_key(struct sk_buff *skb, struct bpf_tunnel_key *key, u32 size, u64 flags)

获取隧道（外层报文）的元数据，skb关联的封包的隧道元数据被填充到key，长度size。标记BPF_F_TUNINFO_IPV6提示隧道是基于IPv6而非IPv4。

bpf_tunnel_key

对端的IP地址被存放在

key->remote_ipv4

key->remote_ipv6

通过

key->tunnel_id

bpf_skb_set_tunnel_key()

下面这个示例用在隧道一端的TC Ingress接口，可以过滤掉对端隧道IP不是10.0.0.1的封包：

int ret;
struct bpf_tunnel_key key = {};

ret = bpf_skb_get_tunnel_key(skb, &key, sizeof(key), 0);
if (ret < 0)
        return TC_ACT_SHOT;     // drop packet

if (key.remote_ipv4 != 0x0a000001)
        return TC_ACT_SHOT;     // drop packet

return TC_ACT_OK;               // accept packet

支持VxLAN、Geneve、GRE、IPIP等类型的隧道。

签名：

int bpf_skb_set_tunnel_key(struct sk_buff *skb, struct bpf_tunnel_key *key, u32 size, u64 flags)

为skb关联的封包生成隧道元数据。隧道元数据被设置为长度为size的bpf_tunnel_key结构。flags是如下位域的组合：

1. BPF_F_TUNINFO_IPV6 指示隧道基于IPv6而非IPv4
2. BPF_F_ZERO_CSUM_TX 对于IPv4封包，添加一个标记到隧道元数据，提示应该跳过Checksum计算，将其置零
3. BPF_F_DONT_FRAGMENT，添加一个标记到隧道元数据，提示封包不得被分片（fragmented）
4. BPF_F_SEQ_NUMBER，添加一个标记到隧道元数据，提示发送封包之前，需要添加sequence number

示例：

struct bpf_tunnel_key key;
// populate key ...
bpf_skb_set_tunnel_key(skb, &key, sizeof(key), 0);
bpf_clone_redirect(skb, vxlan_dev_ifindex, 0);

签名：

int bpf_skb_get_tunnel_opt(struct sk_buff *skb, u8 *opt, u32 size)

从skb关联的封包中获取隧道选项元数据，并且将原始的隧道选项信息存储到大小为size的opt中。

签名：

int bpf_skb_set_tunnel_opt(struct sk_buff *skb, u8 *opt, u32 size)

将隧道选项元数据设置给skb关联的封包。

签名：

int bpf_skb_change_proto(struct sk_buff *skb, __be16 proto, u64 flags)

将skb的协议改为proto。目前仅仅支持将IPv4改为IPv6。助手函数会做好底层工作，例如修改套接字缓冲的大小。eBPF程序需要调用

skb_store_bytes

bpf_l3_csum_replace

bpf_l4_csum_replace

该助手函数的主要意义是执行一个NAT64操作。

在内部实现上，封包的GSO（generic segmentation offload）类型标记为dodgy，因而报文头被检查，TCP分段被GSO/GRO引擎重新分段。

flags必须清零，这个参数暂时没有使用。

调用此助手函数会导致封包缓冲区改变，因此在加载期间校验器对指针的校验将失效，必须重新校验。

签名：

s64 bpf_csum_diff(__be32 *from, u32 from_size, __be32 *to, u32 to_size, __wsum seed)

计算两个缓冲区from到to的checksum difference。

签名：

int bpf_skb_change_type(struct sk_buff *skb, u32 type)

修改封包类型，即设置

skb->pkt_type

1. PACKET_HOST 单播给本机的封包
2. PACKET_BROADCAST 广播封包
3. PACKET_MULTICAST 组播封包
4. PACKET_OTHERHOST单播给其它机器的封包

签名：

int bpf_skb_change_head(struct sk_buff *skb, u32 len, u64 flags)

增长封包的headroom，增长len长度，调整MAC头的偏移量。如果需要，该函数会自动扩展和重新分配内存。

该函数可以用于在L3的skb上，推入一个MAC头，然后将其重定向到L2设备。

flags为保留字段，全部置空。

调用此助手函数会导致封包缓冲区改变，因此在加载期间校验器对指针的校验将失效，必须重新校验。

签名：

int bpf_skb_under_cgroup(struct sk_buff *skb, struct bpf_map *map, u32 index)

检查skb是否是由BPF_MAP_TYPE_CGROUP_ARRAY类型的Map的index位置所指向的CGroup2的descendant。

返回值：

0 ：不是目标Cgroup2的descendant
1：是目标Cgroup2的descendant
负数：出错

签名：

void bpf_set_hash_invalid(struct sk_buff *skb)

无效化

skb->hash

签名：

u32 bpf_get_hash_recalc(struct sk_buff *skb)

获取封包哈希值

skb->hash

调用bpf_set_hash_invalid()、bpf_skb_change_proto()、bpf_skb_store_bytes()+BPF_F_INVALIDATE_HASH标记，都会导致哈希值清空，并导致下一次bpf_get_hash_recalc()调用重新生成哈希值。

签名：

u32 bpf_set_hash(struct sk_buff *skb, u32 hash)

设置完整哈希值到skb->hash

签名：

int bpf_skb_change_tail(struct sk_buff *skb, u32 len, u64 flags)

Resize(trim/grow) skb关联的封包到len长。flags必须置零。

改变封包长度后，eBPF程序可能需要调用bpf_skb_store_bytes、bpf_l3_csum_replace、bpf_l3_csum_replace等函数填充数据、重新计算Checksum。

一般用于回复ICMP控制报文。

调用此助手函数会导致封包缓冲区改变，因此在加载期间校验器对指针的校验将失效，必须重新校验。

签名：

int bpf_skb_pull_data(struct sk_buff *skb, u32 len)

所谓non-linear的skb，是指被fragmented的skb，即有一部分数据没有存放在skb所在内存，而是存放在其它内存页（可能有多个），并通过skb_shared_info记录这些数据位置。

当skb是non-linear的、并且不是所有len长是linear section的一部分的前提下，拉取skb的non-linear数据。确保skb的len字节是可读写的。如果len设置为0，则拉取拉取skb的整个长度的数据。

进行封包直接访问时，通过

skb->data_end

1. 偏移量是无效的
2. 偏移量对应的数据是在skb的non-linear部分中

该助手函数可以用来一次性拉取non-linear数据，然后再进行偏移量测试和数据访问。

此函数确保skb是uncloned，这是直接封包访问的前提。

调用此助手函数会导致封包缓冲区改变，因此在加载期间校验器对指针的校验将失效，必须重新校验。

签名：

u64 bpf_get_socket_cookie(struct sk_buff *skb)

如果skb关联到一个已知的套接字，则得到套接字的cookie（由内核生成），如果尚未设置cookie，则生成之。一旦cookie生成，在套接字的生命周期范围内都不会改变。

该助手用于监控套接字网络流量统计信息，它在网络命名空间范围内为套接字提供唯一标识。

签名：

u32 bpf_get_socket_uid(struct sk_buff *skb)

获得套接字的owner UID。如果套接字是NULL，或者不是full socket（time-wait状态，或者是一个request socket），则返回overflowuid，overflowuid不一定是socket的实际UID。

签名：

s64 bpf_csum_update(struct sk_buff *skb, __wsum csum)

如果驱动已经为整个封包提供了Checksum，那么此函数将csum加到

skb->csum

该助手函数应当和

bpf_csum_diff()

签名：

u32 bpf_get_route_realm(struct sk_buff *skb)

得到路由的Realm，也就是skb的destination的tclassid字段。这个字段是用户提供的一个tag，类似于net_cls的classid。不同的是，这里的tag关联到路由条目（destination entry）。

可以在clsact TC egress钩子中调用此函数，或者在经典的classful egress qdiscs上使用。不能在TC ingress路径上使用。

要求内核配置选项CONFIG_IP_ROUTE_CLASSID。

返回skb关联的封包的路由的realm。

签名：

int bpf_setsockopt(struct bpf_sock_ops *bpf_socket, int level, int optname, char *optval, int optlen)

针对bpf_socket关联的套接字发起一个setsockopt()操作，此套接字必须是full socket。optname为选项名，optval/optlen指定了选项值，level指定了选项的位置。

该函数实际上实现了setsockopt()的子集，支持以下level：

1. SOL_SOCKET，支持选项SO_RCVBUF, SO_SNDBUF, SO_MAX_PACING_RATE, SO_PRIORITY, SO_RCVLOWAT, SO_MARK
2. IPPROTO_TCP，支持选项TCP_CONGESTION, TCP_BPF_IW, TCP_BPF_SNDCWND_CLAMP
3. IPPROTO_IP，支持选项IP_TOS
4. IPPROTO_IPV6，支持选项IPV6_TCLASS

签名：

int bpf_skb_adjust_room(struct sk_buff *skb, u32 len_diff, u32 mode, u64 flags)

增加/缩小skb关联的封包的数据的room，增量为len_diff。mode可以是：

1. BPF_ADJ_ROOM_NET，在网络层调整room，即在L3头上增加/移除room space

flags必须置零。

调用此助手函数会导致封包缓冲区改变，因此在加载期间校验器对指针的校验将失效，必须重新校验。

签名：

int bpf_xdp_adjust_head(struct xdp_buff *xdp_md, int delta)

移动

xdp_md->data

该函数准备用于push/pop headers的封包。

调用此助手函数会导致封包缓冲区改变，因此在加载期间校验器对指针的校验将失效，必须重新校验。

签名：

int bpf_xdp_adjust_meta(struct xdp_buff *xdp_md, int delta)

调整 xdp_md->data_meta所指向的地址delta字节。该操作改变了存储在xdp_md->data中的地址信息。

签名：

u64 bpf_get_current_task(void)

获取当前Task结构的指针。

签名：

int bpf_get_stackid(struct pt_reg *ctx, struct bpf_map *map, u64 flags)

获取一个用户/内核栈，得到其ID。需要传入ctx，即当前追踪程序在其中执行的上下文对象，以及一个BPF_MAP_TYPE_STACK_TRACE类型的Map。通过flags指示需要跳过多少栈帧（0-255），masked with BPF_F_SKIP_FIELD_MASK。flags的其它位如下：

1. BPF_F_USER_STACK 收集用户空间的栈，而非内核栈
2. BPF_F_FAST_STACK_CMP 基于哈希来对比栈
3. BPF_F_REUSE_STACKID 如果两个不同的栈哈希到同一个stackid，丢弃旧的

签名：

u64 bpf_get_current_pid_tgid(void)

返回一个包含了当前tgid和pid的64bit整数。值为

current_task->tgid << 32 | current_task->pid

签名：

u64 bpf_get_current_uid_gid(void)

返回一个包含了当前GID和UID的整数。值为

current_gid << 32 | current_uid

签名：

int bpf_get_current_comm(char *buf, u32 size_of_buf)

将当前任务的comm属性拷贝到长度为size_of_buf的buf中。comm属性包含可执行文件的路径

调用成功时助手函数确保buf是NULL-terminated。如果失败，则填满0

签名：

u32 bpf_get_cgroup_classid(struct sk_buff *skb)

得到当前任务的classid，即skb所属的net_cls控制组的classid。该助手函数可用于TC的egress路径，不能用于ingress路径。

Linux支持两个版本的Cgroups，v1和v2，用户可以混合使用。但是，net_cls是v1特有的Cgroup。这意味着此助手函数和run on cgroups（v2 only）的eBPF程序不兼容，套接字一次仅仅能携带一个版本Cgroup的数据。

内核必须配置CONFIG_CGROUP_NET_CLASSID=y/m才能使用此助手函数。

返回classid，或者0，即默认的没有被配置的classid。

签名：

int bpf_probe_write_user(void *dst, const void *src, u32 len)

尝试在以一个安全方式来写入src的len字节到dst中。仅仅对于运行在用户上下文的线程可用，dst必须是有效的用户空间地址。

由于TOC-TOU攻击的原因，此助手函数不得用于实现任何类型的安全机制。

此函数用于试验目的，存在的导致系统、进程崩溃的风险。当调用了此函数的eBPF程序被挂钩后，内核日志会打印一条警告信息，包含PID和进程名信息。

签名：

int bpf_probe_read_str(void *dst, int size, const void *unsafe_ptr)

从unsafe_ptr拷贝一个NULL结尾的字符串到dst，size包含结尾的NULL字符。如果字符串长度小于size，不会补NUL；如果字符串长度大于size，则截断（保证填充字符串结尾NULL）

签名：

int bpf_current_task_under_cgroup(struct bpf_map *map, u32 index)

检查当前正在运行的探针是否在map的index所指向的Cgroup2之下。

签名：

int bpf_get_numa_node_id(void)

得到当前NUMA节点的ID。该函数的主要目的是用于选取本地NUMA节点的套接字。

签名：

int bpf_perf_event_output(struct pt_reg *ctx, struct bpf_map *map, u64 flags, void *data, u64 size)

将长度为size的blob写入到Map所存放的特殊BPF perf event。map的类型是BPF_MAP_TYPE_PERF_EVENT_ARRAY

perf event必须具有属性：

sample_type = PERF_SAMPLE_RAW
type = PERF_TYPE_SOFTWARE
config = PERF_COUNT_SW_BPF_OUTPUT

flags用于指定写入到数组的索引。masked by BPF_F_INDEX_MASK，如果指定BPF_F_CURRENT_CPU则取当前CPU的值。

当前程序的ctx也需要传递给助手函数。

在用户空间，希望读取值的程序需要针对perf event调用perf_event_open() ，然后将文件描述符存储到Map中。这个操作必须在eBPF程序第一次写入数据到Map之前完成。参考内核中的例子samples/bpf/trace_output_user.c 

要和用户空间进行数据交互，该函数优于bpf_trace_printk()，性能更好。适合从eBPF程序stream数据给用户空间读取。

签名：

u64 bpf_perf_event_read(struct bpf_map *map, u64 flags)

读取一个perf event counter的值，该助手函数操作BPF_MAP_TYPE_PERF_EVENT_ARRAY类型的Map。这个Map本质上是一个数组，它的size和CPU数量一致，其值和对应CPU相关。取哪个CPU的值，masked by BPF_F_INDEX_MASK，如果指定BPF_F_CURRENT_CPU则取当前CPU的值。

在4.13之前，仅仅支持hardware perf event。

成功时返回计数器值，否则返回负数。

考虑使用

bpf_perf_event_read_value

一个BPF Application由1-N个BPF program、BPF Maps、全局变量组成。所有BPF program（各自对应一个ELF section）、用户空间（的控制）程序可以共享Map/全局变量。

BPF Application通常会经历以下生命周期阶段：

1. Open：控制程序打开BPF object文件，解析了programs/map/global vars，但是尚未在内核中创建这些对象。打开BPF object文件后，控制程序可能进行一些调整，例如设置程序类型、设置全局变量的值，等等
2. Load：在此阶段，BPF Maps被创建，各种relocations被解析，BPF programs被载入内核并校验。这个阶段结束时，BPF程序的所有组件都被校验并且存在于内核，但是BPF program还不会被内核执行，可以保证在没有竞态条件的前提下，对BPF Map进行初始化
3. Attach：BPF programs被挂钩到相应的BPF挂钩点（例如tracepoint、kprobes、cgroup hooks、网络封包处理流水线…），BPF program开始工作，读写BPF Maps和全局变量
4. Teardown：BPF程序被detach并unload，BPF Map被销毁

通过bpftool生成的BPF Skeleton，包含了触发上述阶段的函数：

1. <name>__open()

   ：创建并打开BPF Application

2. <name>__load()

   ：实例化、加载、校验BPF Application组件

3. <name>__attach()

   ：将BPF programs挂钩到内核的hook point。你也可以选择直接使用libbpf API进行细粒度控制

4. <name>__destroy()

   ：销毁BPF programs并释放所有资源

在内核空间，访问全局变量使用普通的C语法，你甚至可以取地址并将其传递给助手函数。

在控制程序中，你需要通过BPF skeleton来访问这些变量：

1. skel->rodata

   ，访问只读变量（常量）

2. skel->bss

   ，访问可变的、以0初始化的变量

3. skel->data

   ，访问可变的、非0初始化的变量

在用户空间对这些变量的修改，会立刻反映到内核空间。

BPF ring buffer是一个新的BPF数据结构，它解决了BPF perf buffer（现有的给用户空间发送数据的事实标准工具）的内存效率、事件re-ordering问题。

ringbuf提供了兼容perfbuf的API，便于迁移。同时也提供了新的reserve/commit API，具有更好的易用性。

当BPF程序将收集的信息发送到用户空间，供后续处理时，通常会利用perfbuf。perfbuf是per-CPU的环形缓冲区，允许内核和用户空间进行高效的数据交换。但是由于它的per-CPU设计，会导致两个缺点：内存低效、事件乱序。

因为这些缺点，内核5.8+开始，BPF提供了新的数据结构，BPF ring buffer。它是一个多生产者、单消费者（MPSC）的队列，可以安全的被多CPU环境共享。

ringbuf支持perfbuf的特性：

1. 可变长度数据记录
2. 基于内存映射区域，高效的从用户空间读取数据的能力，不需要内存拷贝或者执行系统调用
3. 支持epoll通知，或者忙循环（最小化延迟）

perfbuf为每个CPU都分配了独立的缓冲区，开发者可能需要进行权衡：

1. 如果分配足够大的缓冲，则会浪费内存，特别是核心数很多的情况下
2. 如果分配较小的缓冲，那么出现事件spike时，会丢失数据

而ringbuf使用单个缓冲区，因而能够容易应对spike，同时不需要太大的内存消耗。

在追踪相关事件（例如进程启动/退出、网络连接生命周期事件）的时候，事件顺序非常重要。

使用perfbuf时，如果两个相关事件在很短事件内（若干ms）被不同CPU处理，则可能发出到用户空间的顺序是错乱的。

在所有应用场景下，BPF ringbuf都有着和perfbuf可比较的性能。

唯一需要考虑使用perfbuf的场景是在NMI (non-maskable interrupt)上下文下运行的BPF程序，例如处理cpu-cycles之类的perf事件。由于ringbuf内部使用一个轻量的自旋锁，在NMI上下文下可能发生锁争用并导致reserve失败。

为了简化代码的迁移，ringbuf提供了一套类似于perfbuf的API，本节做一个对比。

下面的数据结构代表BPF程序需要收集的一个事件：

#define TASK_COMM_LEN 16
#define MAX_FILENAME_LEN 512

struct event {
	int pid;
	char comm[TASK_COMM_LEN];
	char filename[MAX_FILENAME_LEN];
};

perfbuf和ringbuf对应不同的Map类型：

/*** perfbuf ***/
struct {
    __uint(type, BPF_MAP_TYPE_PERF_EVENT_ARRAY);
    __uint(key_size, sizeof(int));
    __uint(value_size, sizeof(int));
} pb SEC(".maps");

/*** ringbuf ***/
struct {
    __uint(type, BPF_MAP_TYPE_RINGBUF);
    // 和perfbuf不同，ringbuf的尺寸可以在内核端定义
    // 但是，在用户空间也可以通过bpf_map__set_max_entries()指定或覆盖ringbuf的尺寸
    // 单位是字节，必须是内核页（一般都是4KB）大小的整数倍，并且是2的幂
    __uint(max_entries, 256 * 1024 /* 256 KB */);
} rb SEC(".maps");

由于event超过512字节，因此不能直接在栈上分配，需要存储到BPF_MAP_TYPE_PERCPU_ARRAY：

struct {
	__uint(type, BPF_MAP_TYPE_PERCPU_ARRAY);
	__uint(max_entries, 1);  // 只需要1个元素即可
	__type(key, int);
	__type(value, struct event);
} heap SEC(".maps");

内核空间代码：

// 挂钩到sched:sched_process_exec，每当成功的exec()系统调用后触发
SEC("tp/sched/sched_process_exec")
int handle_exec(struct trace_event_raw_sched_process_exec *ctx)
{
	unsigned fname_off = ctx->__data_loc_filename & 0xFFFF;
	struct event *e;
	int zero = 0;
	// 获得事件的指针
	e = bpf_map_lookup_elem(&heap, &zero);
	if (!e) /* can't happen */
		return 0;

	// 填充字段
	e->pid = bpf_get_current_pid_tgid() >> 32;
	bpf_get_current_comm(&e->comm, sizeof(e->comm));
	bpf_probe_read_str(&e->filename, sizeof(e->filename), (void *)ctx + fname_off);

	/*** 填充数据的API不同 ***/
	/*** perfbuf ***/
	// 输出追踪样本，要求在perfbuf中保留e大小的缓冲区，然后通知用户空间有数据可用
	bpf_perf_event_output(ctx, &pb, BPF_F_CURRENT_CPU, e, sizeof(*e));
        /*** ringbuf ***/
	// 不需要传递ctx对象
	bpf_ringbuf_output(&rb, e, sizeof(*e), 0);

	return 0;
}

用户空间代码：

struct perf_buffer *pb = NULL;
struct perf_buffer_opts pb_opts = {};
struct perfbuf_output_bpf *skel;

/*** 回调函数的签名不同 ***/
/*** perfbuf ***/
void handle_event(void *ctx, int cpu, void *data, unsigned int data_sz)
{
    const struct event *e = data;
    struct tm *tm;
    char ts[32];
    time_t t;
    time(&t);
    tm = localtime(&t);
    strftime(ts, sizeof(ts), "%H:%M:%S", tm);

    printf("%-8s %-5s %-7d %-16s %s\n", ts, "EXEC", e->pid, e->comm, e->filename);
}
/*** ringbuf ***/
int handle_event(void *ctx, void *data, size_t data_sz)
{
    // ...
}

/*** 创建用户空间缓冲区的API不同 ***/
/*** perfbuf ***/
pb_opts.sample_cb = handle_event; // 回调函数
//                    指向内核空间对应物，也就是那个Map
//                                                为每个CPU分配8个页，也就是32KB的缓冲区
pb = perf_buffer__new(bpf_map__fd(skel->maps.pb), 8 /* 32KB per CPU */, &pb_opts);
if (libbpf_get_error(pb)) {
    err = -1;
    fprintf(stderr, "Failed to create perf buffer\n");
    goto cleanup;
}
/*** ringbuf ***/
rb = ring_buffer__new(bpf_map__fd(skel->maps.rb), handle_event, NULL, NULL);
if (!rb) {
    err = -1;
    fprintf(stderr, "Failed to create ring buffer\n");
    goto cleanup;
}


// 开始epoll轮询
while (!exiting) {
    /*** 轮询接口不同 ***/
    /*** perfbuf ***/
    err = perf_buffer__poll(pb, 100 /* timeout, ms */);
    /*** ringbuf ***/
    err = ring_buffer__poll(rb, 100 /* timeout, ms */);
    
    // ...
}

上面的perfbuf兼容API，具有与perfbuf类似的缺点：

1. 额外的内存拷贝：你需要额外的内存空间来构建追踪样本对象，然后才能将它拷贝到缓冲区中
2. very late data reservation：构建（可能需要采集多种内存数据）追踪样本对象的工作可能是无意义的，如果缓冲区中剩余空间（由于用户空间程序处理缓慢或者事件burst）不足，构建的对象无处存放。使用xxx_output()接口不能提前感知缓冲区剩余空间，从而避免不必要的样本对象构造

ringbuf提供了一套新的API，应对上述缺点。

1. bpf_ringbuf_reserve()

   ：尝试在缓冲区中预定空间，这个操作可以在构建样本对象之前就进行，尽早获取空间不足的状况。如果预定成功，则返回指针，并且可以保证后续可以将数据commit到其中；如果预定失败，则返回NULL，我们可以跳过后续的、无意义的操作

2. bpf_ringbuf_commit()

   ：将样本对象发送到缓冲区

此外，reserve的空间，在commit之前，对于用户空间是不可见的。因此你可以直接用它来构造样本对象，不用担心半初始化的对象被看到，同时达到节约内存的目的。

唯一的限制是：reserve的空间大小，必须能够被BPF verifier感知（常量）。如果样本尺寸是动态的，则只能使用

bpf_ringbuf_output()

用法示例：

// 不再需要到per-CPU array中预先构造对象：
//   e = bpf_map_lookup_elem(&heap, &zero);
e = bpf_ringbuf_reserve(&rb, sizeof(*e), 0);

// 不再需要将per-CPU array中的对象拷贝到缓冲区
//   bpf_ringbuf_output(&rb, e, sizeof(*e), 0);
bpf_ringbuf_submit(e, 0);

不管是perfbuf还是ringbuf，如果内核每写入一个样本，就通知（也就是唤醒在poll/epoll上等待的）用户空间程序，其开销是相当大的。

perfbuf的解决办法是，允许用户空间程序构造perfbuf时，指定每发生N个样本才唤醒一次，这可能会让你丢失最多N-1个样本。

ringbuf则允许为

bpf_ringbuf_output()

bpf_ringbuf_commit()

1. BPF_RB_FORCE_WAKEUP 本次写入样本，强制唤醒用户空间程序
2. BPF_RB_NO_WAKEUP本次写入样本，不会唤醒用户空间程序

如果不指定上述标记，ringbuf会根据用户空间程序lagging的情况决定是否唤醒。不指定标记通常是安全的默认值。

BPF没有常规的调试工具，支持设置断点、探查变量、单步跟踪的那种。

使用

bpf_printk(fmt, args...)

/sys/kernel/debug/tracing/trace_pipe

这个函数的成本很高，不能在生产环境使用。

助手函数

long bpf_trace_printk(const char *fmt, __u32 fmt_size, ...)

这是libbpf提供的脚手架，可以让你快速开始编写自己的eBPF程序。该脚手架目前提供一些demo程序：

1. minimal：最小化的、能编译、加载、运行的BPF hello world程序
2. bootstrap：现实可用的、可移植的、全功能的BPF程序，依赖BPF CO-RE。需要当前使用的内核开启

   CONFIG_DEBUG_INFO_BTF=y

   ，该demo还示例了5.5+支持的BPF全局变量、5.8+支持的BPF ring buffer

libbpf-bootstrap自带了libbpf（作为git子模块）和bpftool（仅x84），避免依赖你的Linux发行版所携带的特定版本。libbpf依赖的库包括libelf、zlib，需要确保已经安装。

执行下面的命令获得脚手架：

git clone https://github.com/libbpf/libbpf-bootstrap.git
git submodule init

目录结构如下：

.
├── examples
│   ├── c  # C代码示例
│   │   ├── bootstrap.bpf.c  # 在内核空间执行的BPF程序
│   │   ├── bootstrap.c      # 在用户空间执行的逻辑，负责加载BPF字节码，在程序生命周期内和BPF程序交互
│   │   ├── bootstrap.h      # 用户/内核空间程序共享的头
│   │   ├── CMakeLists.txt
│   │   ├── fentry.bpf.c
│   │   ├── fentry.c
│   │   ├── kprobe.bpf.c
│   │   ├── kprobe.c
│   │   ├── Makefile
│   │   ├── minimal.bpf.c
│   │   ├── minimal.c
│   │   ├── uprobe.bpf.c
│   │   ├── uprobe.c
│   │   └── xmake.lua
│   └── rust # Rust代码示例
│       ├── Cargo.lock
│       ├── Cargo.toml
│       └── xdp
│           ├── build.rs
│           ├── Cargo.lock
│           ├── Cargo.toml
│           └── src
│               ├── bpf
│               │   ├── vmlinux.h -> ../../../../../vmlinux/vmlinux.h
│               │   └── xdppass.bpf.c
│               └── main.rs
├── libbpf # 自带的libbpf
├── LICENSE
├── README.md
├── tools  # 自带bpftool，用于为你的BPF代码构建BPF skeleton、生成vmlinux.h头
│   ├── bpftool
│   ├── cmake
│   │   ├── FindBpfObject.cmake
│   │   └── FindLibBpf.cmake
│   └── gen_vmlinux_h.sh  # 用于生成自定义的vmlinux.h
└── vmlinux
    ├── vmlinux_508.h
    └── vmlinux.h -> vmlinux_508.h  # 预生成的vmlinux.h

最小化的样例，不依赖BPF CO-RE，可以在很老版本的内核上运行。该程序会安装一个每秒触发一次的tracepoint handler，它使用

bpf_printk()

构建此样例：

cd examples/c
make minimal

内核空间代码：

// 包含基本的BPF相关的类型和常量。为了使用内核空间BPF API，例如助手函数的flags，需要引入此头
#include <linux/bpf.h>
// 由libbpf提供，包含了大部分常用宏、常量、助手函数，几乎每个BPF程序都会使用
#include <bpf/bpf_helpers.h>
// 这个变量定义你的代码的License，内核强制要求此字段存在，某些功能对于非GPL兼容的License不可用
//             必须定义在license段
char LICENSE[] SEC("license") = "Dual BSD/GPL";
// 全局变量，要求内核版本5.5+，全局变量甚至可以从用户空间读写
// 可以用于配置BPF程序、存放轻量的统计数据、在内核和用户空间传递数据
int my_pid = 0;

// 这里定义了BPF内核程序
// 这个注解，说明了需要创建的BPF程序类型，以及如何挂钩到内核
//   tracepoint BPF程序
//      在进入write系统调用时触发
SEC("tp/syscalls/sys_enter_write")
int handle_tp(void *ctx)
{
	// 调用助手函数，获得PID（内核的术语叫TGID）。为了节约空间，很多助手函数使用高低字节存储不同的数据
	int pid = bpf_get_current_pid_tgid() >> 32;

	// 判断是否是关注进程发出的系统调用
	if (pid != my_pid)
		return 0;
	// 如果是，打印信息到/sys/kernel/debug/tracing/trace_pipe
	// 注意，由于性能问题，这个函数不能用于生产环境
	bpf_printk("BPF triggered from PID %d.\n", pid);

	return 0;
}

// 你还可以定义更多的BPF程序，只需要为它们声明适当的SEC即可。所有这些程序共享全局变量

用户空间代码：

#include <stdio.h>
#include <unistd.h>
#include <sys/resource.h>
#include <bpf/libbpf.h>
// 由bpftool自动生成的，映射了minimal.bpf.c的高层结构的BPF skeleton
// 编译后的BPF object被内嵌到此头文件（也就是用户空间代码）中，简化了开发和部署
// 文件路径 .output/<app>.skel.h
#include "minimal.skel.h"

// 此回调打印libbpf日志到控制台
static int libbpf_print_fn(enum libbpf_print_level level, const char *format, va_list args)
{
	return vfprintf(stderr, format, args);
}

static void bump_memlock_rlimit(void)
{
	struct rlimit rlim_new = {
		.rlim_cur	= RLIM_INFINITY,
		.rlim_max	= RLIM_INFINITY,
	};

	if (setrlimit(RLIMIT_MEMLOCK, &rlim_new)) {
		fprintf(stderr, "Failed to increase RLIMIT_MEMLOCK limit!\n");
		exit(1);
	}
}

int main(int argc, char **argv)
{
	struct minimal_bpf *skel;
	int err;

	// 为所有libbpf日志设置回调函数
	libbpf_set_print(libbpf_print_fn);

	// 增大内核内部的per-user内存限制，允许BPF子系统为程序、Map分配足够的资源
	bump_memlock_rlimit();

	// 打开BPF skeleton
	skel = minimal_bpf__open();
	if (!skel) {
		fprintf(stderr, "Failed to open BPF skeleton\n");
		return 1;
	}

	// 访问BSS段中的全局变量
	skel->bss->my_pid = getpid();

	// 加载和校验BPF程序
	err = minimal_bpf__load(skel);
	if (err) {
		fprintf(stderr, "Failed to load and verify BPF skeleton\n");
		goto cleanup;
	}

	// 挂钩BPF程序，在此即注册tracepoint handler
	// libbpf能够根据SEC注解，自动的为大部分BPF程序类型（tracepoints, kprobes等）选择适当的挂钩点
	// 如果不能满足需求，可以调用libbpf提供的函数手工挂钩的API
	err = minimal_bpf__attach(skel);
	if (err) {
		fprintf(stderr, "Failed to attach BPF skeleton\n");
		goto cleanup;
	}

	printf("Successfully started! Please run `sudo cat /sys/kernel/debug/tracing/trace_pipe` "
	       "to see output of the BPF programs.\n");

	// 触发write系统调用，进而触发BPF程序
	for (;;) {
		/* trigger our BPF program */
		fprintf(stderr, ".");
		sleep(1);
	}

cleanup:
	// 清除所有内核/用户空间的资源
	// 在大部分情况下，即使程序崩溃，没有清理，内核也会作自动清理
	minimal_bpf__destroy(skel);
	return -err;
}

构建此程序的Makefile：

# SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
OUTPUT := .output
CLANG ?= clang
LLVM_STRIP ?= llvm-strip
BPFTOOL ?= $(abspath ../../tools/bpftool)
LIBBPF_SRC := $(abspath ../../libbpf/src)
LIBBPF_OBJ := $(abspath $(OUTPUT)/libbpf.a)
# vmlinux.h由bpftool从当前运行的内核中抽取出，包含了所有内核使用的类型定义
VMLINUX := ../../vmlinux/vmlinux.h
# 使用自己的libbpf API头文件、Linux UAPI头文件，避免依赖当前系统的（可能缺失或过期的）头文件
INCLUDES := -I$(OUTPUT) -I../../libbpf/include/uapi -I$(dir $(VMLINUX))
# 使用-g保留调试信息
CFLAGS := -g -Wall
# 体系结构信息会传递给后续的BPF构建步骤，使用bpf_tracing.h中低级别tracing助手函数需要此信息
ARCH := $(shell uname -m | sed 's/x86_64/x86/')

# 这个示例项目包含多个demo，每个对应一个APP
APPS = minimal bootstrap uprobe kprobe fentry

# 获取Clang在当前系统上默认的includes目录，当以-target bpf编译时，这些目录被显式添加到
# include列表。如果不这样做，某些体系结构/发行版下，体系结构特定的目录可能missing，诸如
# asm/types.h, asm/byteorder.h, asm/socket.h, asm/sockios.h, sys/cdefs.h之类
# 的头文件可能missing
CLANG_BPF_SYS_INCLUDES = $(shell $(CLANG) -v -E - </dev/null 2>&1 \
	| sed -n '/<...> search starts here:/,/End of search list./{ s| \(/.*\)|-idirafter \1|p }')

ifeq ($(V),1)
	Q =
	msg =
else
	Q = @
	msg = @printf '  %-8s %s%s\n'					\
		      "$(1)"						\
		      "$(patsubst $(abspath $(OUTPUT))/%,%,$(2))"	\
		      "$(if $(3), $(3))";
	MAKEFLAGS += --no-print-directory
endif

.PHONY: all
all: $(APPS)

.PHONY: clean
clean:
	$(call msg,CLEAN)
	$(Q)rm -rf $(OUTPUT) $(APPS)

$(OUTPUT) $(OUTPUT)/libbpf:
	$(call msg,MKDIR,$@)
	$(Q)mkdir -p $@

# 1. 构建 libbpf 为静态库，存放在.output目录下
#    如果希望和系统的libbpf共享库链接，去掉这个目标
$(LIBBPF_OBJ): $(wildcard $(LIBBPF_SRC)/*.[ch] $(LIBBPF_SRC)/Makefile) | $(OUTPUT)/libbpf
	$(call msg,LIB,$@)
	$(Q)$(MAKE) -C $(LIBBPF_SRC) BUILD_STATIC_ONLY=1		      \
		    OBJDIR=$(dir $@)/libbpf DESTDIR=$(dir $@)		      \
		    INCLUDEDIR= LIBDIR= UAPIDIR=			      \
		    install

# 2. 构建BPF object
$(OUTPUT)/%.bpf.o: %.bpf.c $(LIBBPF_OBJ) $(wildcard %.h) $(VMLINUX) | $(OUTPUT)
	$(call msg,BPF,$@)
	# 必须使用-g -O2     目标必须是bpf 为bpf_tracing.h定义必要的宏
	# 
	$(Q)$(CLANG) -g -O2 -target bpf -D__TARGET_ARCH_$(ARCH) $(INCLUDES) $(CLANG_BPF_SYS_INCLUDES) -c $(filter %.c,$^) -o $@
	$(Q)$(LLVM_STRIP) -g $@ # 去除DWARF信息，从来不会用到。由于BPF程序最终以文本形式嵌入到BPF skeleton，因此要尽量精简

# 3. 生成BPF skeletons, 依赖2
$(OUTPUT)/%.skel.h: $(OUTPUT)/%.bpf.o | $(OUTPUT)
	$(call msg,GEN-SKEL,$@)
	$(Q)$(BPFTOOL) gen skeleton $< > $@

# 4. 构建用户空间程序object，依赖3
$(patsubst %,$(OUTPUT)/%.o,$(APPS)): %.o: %.skel.h

$(OUTPUT)/%.o: %.c $(wildcard %.h) | $(OUTPUT)
	$(call msg,CC,$@)
	$(Q)$(CC) $(CFLAGS) $(INCLUDES) -c $(filter %.c,$^) -o $@

# 5. 构建用户空间程序
$(APPS): %: $(OUTPUT)/%.o $(LIBBPF_OBJ) | $(OUTPUT)
	$(call msg,BINARY,$@)
	$(Q)$(CC) $(CFLAGS) $^ -lelf -lz -o $@

# delete failed targets
.DELETE_ON_ERROR:

# keep intermediate (.skel.h, .bpf.o, etc) targets
.SECONDARY:

minimal是最小化的BPF程序实例，在现代Linux环境下开发BPF程序，bootstrap可以作为一个不错的开始点。它实现的功能包括：

1. 命令行参数解析
2. 信号处理
3. 多个BPF程序之间的交互 —— 通过Map共享状态
4. 使用BPF ring buffer来发送数据到用户空间
5. 用于行为参数化的全局常量，以及如何通过修改段数据初始化常量值
6. 使用BPF CO-RE和vmlinux.h来读取内核

   struct task_struct

   暴露的进程的额外信息

该程序依赖BPF CO-RE，需要内核配置

CONFIG_DEBUG_INFO_BTF=y

公共头文件：

#ifndef __BOOTSTRAP_H
#define __BOOTSTRAP_H

#define TASK_COMM_LEN 16
#define MAX_FILENAME_LEN 127

struct event {
	int pid;
	int ppid;
	unsigned exit_code;
	unsigned long long duration_ns;
	char comm[TASK_COMM_LEN];
	char filename[MAX_FILENAME_LEN];
	bool exit_event;
};

#endif /* __BOOTSTRAP_H */

内核空间代码：

// 该头文件包含内核的所有数据类型，通过gen_vmlinux_h.sh自动生成

// 其中的类型应用了__attribute__((preserve_access_index))注解，可以让Clang
// 生成BPF CO-RE relocations，这让libbpf能够自动的将BPF代码是配到宿主机内核的内存布局，即使
// 该布局和构建BPF程序时候的主机不一致
// BPF CO-RE relocations是创建pre-compiled、可移植的BPF程序的关键，它不需要在目标及其上部署
// Clang/LLVM工具链。一个被选的技术是BCC的运行时编译，这种技术有多个缺点

// 需要注意，vmlinux.h不能和其它系统级的头文件联合适用，会导致类型重定义和冲突
// 因此开发BPF程序时，仅可使用vmlinux.h、libbpf提供的头、你自己定义的头
#include "vmlinux.h"
#include <bpf/bpf_helpers.h>
// 下面两个头文件，用于编写基于BPF CO-RE的追踪应用程序
#include <bpf/bpf_tracing.h>
#include <bpf/bpf_core_read.h>
// 用于/内核空间共享头
#include "bootstrap.h"

char LICENSE[] SEC("license") = "Dual BSD/GPL";

// 定义一个哈希表类型的Map
struct {
	// 这几个__开头的是宏bpf_helpers.h中定义的宏，用来定义结构体字段
	// 定义一个BPF_MAP_TYPE_HASH类型的，最大条目8192的，key类型为pid_t，值类型为u64的Map
	__uint(type, BPF_MAP_TYPE_HASH);
	__uint(max_entries, 8192);
	__type(key, pid_t);
	__type(value, u64);
} exec_start SEC(".maps");
//           为了让libbpf知道它需要创建BPF Map，必须添加此注解

// 定义一个BPF ring buffer类型的Map
// 用于向用户空间发送数据，本样例使用bpf_ringbuf_reserve()/bpf_ringbuf_submit()来实现最高
// 的易用性和性能
struct {
	__uint(type, BPF_MAP_TYPE_RINGBUF);
	__uint(max_entries, 256 * 1024);
} rb SEC(".maps");

// 全局常量，对于用户/内核空间均不可变。在BPF程序校验期间，此常量值已知，BPF Verifier可能依据值来裁减
// 某些dead code
// volatile是必须的，可以防止Clang将变量优化掉（直接没了）
const volatile unsigned long long min_duration_ns = 0;

// 本样例由两个BPF程序组成，这个监控exec系统调用
SEC("tp/sched/sched_process_exec")
int handle_exec(struct trace_event_raw_sched_process_exec *ctx)
{
	struct task_struct *task;
	unsigned fname_off;
	struct event *e;
	pid_t pid;
	u64 ts;

	// 得到当前PID
	pid = bpf_get_current_pid_tgid() >> 32;
	// 获取当前内核时间
	ts = bpf_ktime_get_ns();
	// 记录当前进程的创建时间
	bpf_map_update_elem(&exec_start, &pid, &ts, BPF_ANY);

	/* don't emit exec events when minimum duration is specified */
	if (min_duration_ns)
		return 0;

	// 在ring buffer中保留event长度的空间，返回得到的空间指针
	e = bpf_ringbuf_reserve(&rb, sizeof(*e), 0);
	if (!e)
		return 0;

	// 得到当前Task对象
	task = (struct task_struct *)bpf_get_current_task();
	// 并填充event
	e->exit_event = false;
	e->pid = pid;
	// BPF CO-RE读取
	// 相当于e->ppid = task->real_parent->tgid;
	// 但是对于BPF程序来说，BPF verifier需要额外的检查，因为存在读取任意内核内存的可能
	// BPF_CORE_READ()通过简洁的方式完成此过程，并且记录必要的BPF CO-RE relocations，从而
	// 允许libbpf根据宿主机的内存布局，来调整字段的偏移量
	e->ppid = BPF_CORE_READ(task, real_parent, tgid);
	// 读取当前任务的可执行文件名（不包含路径）
	bpf_get_current_comm(&e->comm, sizeof(e->comm));

	// 获取新进程文件名在ctx的偏移量            移除u32高16位
	fname_off = ctx->__data_loc_filename & 0xFFFF;
	// 从ctx读取文件名，存入e
	bpf_probe_read_str(&e->filename, sizeof(e->filename), (void *)ctx + fname_off);

	// 提交给用户空间供处理
	bpf_ringbuf_submit(e, 0);
	return 0;
}

// 本样例由两个BPF程序组成，这个监控进程退出，即exit系统调用
SEC("tp/sched/sched_process_exit")
int handle_exit(struct trace_event_raw_sched_process_template* ctx)
{
	struct task_struct *task;
	struct event *e;
	pid_t pid, tid;
	u64 id, ts, *start_ts, duration_ns = 0;
	
	// 获取正在退出的进程的PID
	id = bpf_get_current_pid_tgid();
	// 高32位是pid，低32位是线程ID
	pid = id >> 32;
	tid = (u32)id;

	// 如果pid和tid不同，则意味着是非主线程退出，忽略
	if (pid != tid)
		return 0;

	// 查找进程开始时间，并计算进程持续时间
	start_ts = bpf_map_lookup_elem(&exec_start, &pid);
	if (start_ts)
		duration_ns = bpf_ktime_get_ns() - *start_ts;
	else if (min_duration_ns)
		return 0;
	// 从Map删除条目
	bpf_map_delete_elem(&exec_start, &pid);

	// 忽略持续时间过短的进程
	if (min_duration_ns && duration_ns < min_duration_ns)
		return 0;

	// 从ring buffer分配空间
	e = bpf_ringbuf_reserve(&rb, sizeof(*e), 0);
	if (!e)
		return 0;

	// 填充并提交给用户空间处理
	task = (struct task_struct *)bpf_get_current_task();

	e->exit_event = true;
	e->duration_ns = duration_ns;
	e->pid = pid;
	e->ppid = BPF_CORE_READ(task, real_parent, tgid);
	e->exit_code = (BPF_CORE_READ(task, exit_code) >> 8) & 0xff;
	bpf_get_current_comm(&e->comm, sizeof(e->comm));

	/* send data to user-space for post-processing */
	bpf_ringbuf_submit(e, 0);
	return 0;
}

用户空间代码：

#include <argp.h>
#include <signal.h>
#include <stdio.h>
#include <time.h>
#include <sys/resource.h>
#include <bpf/libbpf.h>
#include "bootstrap.h"
#include "bootstrap.skel.h"

// 使用libc的argp做命令行参数解析
static struct env {
	bool verbose;
	long min_duration_ms;
} env;

const char *argp_program_version = "bootstrap 0.0";
const char *argp_program_bug_address = "<bpf@vger.kernel.org>";
const char argp_program_doc[] =
"BPF bootstrap demo application.\n"
"\n"
"It traces process start and exits and shows associated \n"
"information (filename, process duration, PID and PPID, etc).\n"
"\n"
"USAGE: ./bootstrap [-d <min-duration-ms>] [-v]\n";

static const struct argp_option opts[] = {
	{ "verbose", 'v', NULL, 0, "Verbose debug output" },
	{ "duration", 'd', "DURATION-MS", 0, "Minimum process duration (ms) to report" },
	{},
};

static error_t parse_arg(int key, char *arg, struct argp_state *state)
{
	switch (key) {
	case 'v':
		env.verbose = true;
		break;
	case 'd':
		errno = 0;
		env.min_duration_ms = strtol(arg, NULL, 10);
		if (errno || env.min_duration_ms <= 0) {
			fprintf(stderr, "Invalid duration: %s\n", arg);
			argp_usage(state);
		}
		break;
	case ARGP_KEY_ARG:
		argp_usage(state);
		break;
	default:
		return ARGP_ERR_UNKNOWN;
	}
	return 0;
}

static const struct argp argp = {
	.options = opts,
	.parser = parse_arg,
	.doc = argp_program_doc,
};

static int libbpf_print_fn(enum libbpf_print_level level, const char *format, va_list args)
{
	if (level == LIBBPF_DEBUG && !env.verbose)
		return 0;
	return vfprintf(stderr, format, args);
}

static void bump_memlock_rlimit(void)
{
	struct rlimit rlim_new = {
		.rlim_cur	= RLIM_INFINITY,
		.rlim_max	= RLIM_INFINITY,
	};

	if (setrlimit(RLIMIT_MEMLOCK, &rlim_new)) {
		fprintf(stderr, "Failed to increase RLIMIT_MEMLOCK limit!\n");
		exit(1);
	}
}

static volatile bool exiting = false;

static void sig_handler(int sig)
{
	exiting = true;
}

static int handle_event(void *ctx, void *data, size_t data_sz)
{
	// 直接转换为event
	const struct event *e = data;
	struct tm *tm;
	char ts[32];
	time_t t;

	time(&t);
	tm = localtime(&t);
	strftime(ts, sizeof(ts), "%H:%M:%S", tm);

	if (e->exit_event) {
		printf("%-8s %-5s %-16s %-7d %-7d [%u]", ts, "EXIT", e->comm, e->pid, e->ppid, e->exit_code);
		if (e->duration_ns) printf(" (%llums)", e->duration_ns / 1000000);
		printf("\n");
	} else {
		printf("%-8s %-5s %-16s %-7d %-7d %s\n",  ts, "EXEC", e->comm, e->pid, e->ppid, e->filename);
	}
	return 0;
}

int main(int argc, char **argv)
{
	struct ring_buffer *rb = NULL;
	struct bootstrap_bpf *skel;
	int err;

	// 解析命令行参数
	err = argp_parse(&argp, argc, argv, 0, NULL, NULL);
	if (err)
		return err;

	// 日追回调函数
	libbpf_set_print(libbpf_print_fn);

	// 设置RLIMIT_MEMLOCK
	bump_memlock_rlimit();

	// 去除默认Ctrl-C处理逻辑
	signal(SIGINT, sig_handler);
	signal(SIGTERM, sig_handler);

	// 由于有一个常量需要设置值，因此这里没有使用bootstrap_bpf__open_and_load()
	// 而是先open
	skel = bootstrap_bpf__open();
	if (!skel) {
		fprintf(stderr, "Failed to open and load BPF skeleton\n");
		return 1;
	}

	// 然后设置常量值
	skel->rodata->min_duration_ns = env.min_duration_ms * 1000000ULL;

	// 最后load，加载之后，用户空间只能读取，不能修改 skel->rodata->min_duration_ns
	err = bootstrap_bpf__load(skel);
	if (err) {
		fprintf(stderr, "Failed to load and verify BPF skeleton\n");
		goto cleanup;
	}

	// 挂钩BPF程序到内核
	err = bootstrap_bpf__attach(skel);
	if (err) {
		fprintf(stderr, "Failed to attach BPF skeleton\n");
		goto cleanup;
	}

	// 创建ring buffer轮询
	// 映射位ring_buffer类型   内核空间对应物              轮询到数据后的回调
	rb = ring_buffer__new(bpf_map__fd(skel->maps.rb), handle_event, NULL, NULL);
	if (!rb) {
		err = -1;
		fprintf(stderr, "Failed to create ring buffer\n");
		goto cleanup;
	}

	// 打印表头
	printf("%-8s %-5s %-16s %-7s %-7s %s\n",
	       "TIME", "EVENT", "COMM", "PID", "PPID", "FILENAME/EXIT CODE");
	// 接收到信号前，反复轮询
	while (!exiting) {
		err = ring_buffer__poll(rb, 100 /* timeout, ms */);
		/* Ctrl-C will cause -EINTR */
		if (err == -EINTR) {
			err = 0;
			break;
		}
		if (err < 0) {
			printf("Error polling perf buffer: %d\n", err);
			break;
		}
	}

cleanup:
	// 需要清理ring buffer和BPF
	ring_buffer__free(rb);
	bootstrap_bpf__destroy(skel);

	return err < 0 ? -err : 0;
}

上面两个例子都是tracepoint BPF程序。tracepoint是内核中比较稳定的追踪机制，属于静态instrument，它由一系列预定义在内核源码中的挂钩点组成。

kprobe/uprobe则属于动态instrument，在运行时动态的进行instrument，可以对任何函数进行调试追踪。例如在函数的入口、出口地址、或者某一行值入代码，执行到这些代码的时候，你就可以获得上下文信息，例如当前函数的名字、参数、返回值、寄存器甚至全局数据结构信息。

kprobe/uprobe很强大，但是依赖于程序/内核的特定版本，因为函数的签名可能改变，函数也可能被删除。

libbpf-bootstrap提供了一个uprobe样例，此样例能够处理用户空间的entry/exit(return)探针。

内核空间代码：

#include <linux/bpf.h>
#include <linux/ptrace.h>
#include <bpf/bpf_helpers.h>
#include <bpf/bpf_tracing.h>

char LICENSE[] SEC("license") = "Dual BSD/GPL";

// 函数entry探针
SEC("uprobe/func")
// 这里是调用一个宏，在函数体中可以使用参数 struct pt_regs *ctx
//                     逐个列出函数的参数
int BPF_KPROBE(uprobe, int a, int b)
{
	bpf_printk("UPROBE ENTRY: a = %d, b = %d\n", a, b);
	return 0;
}

// 函数exit探针
SEC("uretprobe/func")
//                           列出函数的返回值
int BPF_KRETPROBE(uretprobe, int ret)
{
	bpf_printk("UPROBE EXIT: return = %d\n", ret);
	return 0;
}

用户空间代码：

#include <errno.h>
#include <stdio.h>
#include <unistd.h>
#include <sys/resource.h>
#include <bpf/libbpf.h>
#include "uprobe.skel.h"

//...

/* 通过/proc/self/maps查找进程的base load address, 寻找第一个可执行的（r-xp）内存映射：
 * 绝对起始地址                    此区域的偏移量
 * 5574fd254000-5574fd258000 r-xp 00002000 fd:01 668759                     /usr/bin/cat
 * ^^^^^^^^^^^^                   ^^^^^^^^
 * 绝对起始地址 - 此区域的偏移量 即得到进程的base load address
 */
static long get_base_addr() {
	size_t start, offset;
	char buf[256];
	FILE *f;

	f = fopen("/proc/self/maps", "r");
	if (!f)
		return -errno;

	while (fscanf(f, "%zx-%*x %s %zx %*[^\n]\n", &start, buf, &offset) == 3) {
		if (strcmp(buf, "r-xp") == 0) {
			fclose(f);
			return start - offset;
		}
	}

	fclose(f);
	return -1;
}

// 这个是被追踪的函数
int uprobed_function(int a, int b)
{
	return a + b;
}

int main(int argc, char **argv)
{
	struct uprobe_bpf *skel;
	long base_addr, uprobe_offset;
	int err, i;

	// 注册日志回调钩子、调整rlimit、打开并加载BPF程序

	base_addr = get_base_addr();
	if (base_addr < 0) {
		fprintf(stderr, "Failed to determine process's load address\n");
		err = base_addr;
		goto cleanup;
	}

	// uprobe/uretprobe期望获知被追踪函数的相对偏移量，这个偏移量是相对于process的base load address的
	// 这里直接得到目标函数的绝对地址，然后减去上面我们得到的base load address，即可得到偏移量
	//
	// 通常情况下，被追踪的函数不会在当前程序中，这可能需要解析其所在程序的ELF，
	// 函数相对base load address的偏移量 = .text段的偏移量 + 函数在.text段内的偏移量
	//
	//              得到函数的绝对地址
	uprobe_offset = (long)&uprobed_function - base_addr;

	//                   挂钩
	skel->links.uprobe = bpf_program__attach_uprobe(skel->progs.uprobe,
							false /* entry钩子 */,
							0 /* 到当前进程 */,
							"/proc/self/exe", // 当前进程的二进制文件路径
							uprobe_offset); // 追踪的目标函数的偏移量
	err = libbpf_get_error(skel->links.uprobe);
	if (err) {
		fprintf(stderr, "Failed to attach uprobe: %d\n", err);
		goto cleanup;
	}

	// 这里示例了如何挂钩uprobe/uretprobe到任何现存的/未来创建的、使用同一二进制文件的进程
	skel->links.uretprobe = bpf_program__attach_uprobe(skel->progs.uretprobe,
							   true /* exit钩子 */,
							   -1 /* 任何进程 */,
							   "/proc/self/exe",
							   uprobe_offset);
	err = libbpf_get_error(skel->links.uretprobe);
	if (err) {
		fprintf(stderr, "Failed to attach uprobe: %d\n", err);
		goto cleanup;
	}

	printf("Successfully started! Please run `sudo cat /sys/kernel/debug/tracing/trace_pipe` "
	       "to see output of the BPF programs.\n");

	for (i = 0; ; i++) {
		// 调用目标函数，触发BPF程序
		fprintf(stderr, ".");
		uprobed_function(i, i + 1);
		sleep(1);
	}

cleanup:
	uprobe_bpf__destroy(skel);
	return -err;
}

运行此程序，就可以看到函数uprobed_function每次调用的参数、返回值了。

kprobe和uprobe工作方式很类似，只是挂钩的是内核函数。

libbpf-bootstrap提供了一个kprobe样例，该样例挂钩到do_unlinkat()函数，并且打印PID、文件名、返回值等信息。

内核空间代码：

#include "vmlinux.h"
#include <bpf/bpf_helpers.h>
#include <bpf/bpf_tracing.h>
#include <bpf/bpf_core_read.h>

char LICENSE[] SEC("license") = "Dual BSD/GPL";

// 注解里必须包含目标内核函数的名字
SEC("kprobe/do_unlinkat")
int BPF_KPROBE(do_unlinkat, int dfd, struct filename *name)
{
	pid_t pid;
	const char *filename;

	pid = bpf_get_current_pid_tgid() >> 32;
	// 必须使用此助手函数访问指针参数，fentry则不必
	filename = BPF_CORE_READ(name, name);
	bpf_printk("KPROBE ENTRY pid = %d, filename = %s\n", pid, filename);
	return 0;
}

SEC("kretprobe/do_unlinkat")
int BPF_KRETPROBE(do_unlinkat_exit, long ret)
{
	pid_t pid;

	pid = bpf_get_current_pid_tgid() >> 32;
	bpf_printk("KPROBE EXIT: pid = %d, ret = %ld\n", pid, ret);
	return 0;
}

用户空间代码：

#include <stdio.h>
#include <unistd.h>
#include <signal.h>
#include <string.h>
#include <errno.h>
#include <sys/resource.h>
#include <bpf/libbpf.h>
#include "kprobe.skel.h"

// ...

static volatile sig_atomic_t stop;

static void sig_int(int signo)
{
	stop = 1;
}

int main(int argc, char **argv)
{
	struct kprobe_bpf *skel;
	int err;

	// 注册日志回调钩子、调整rlimit、打开并加载BPF程序

	// 挂钩处理比起uprobe要简单的多，不需要计算目标函数的地址
	err = kprobe_bpf__attach(skel);
	if (err) {
		fprintf(stderr, "Failed to attach BPF skeleton\n");
		goto cleanup;
	}

	if (signal(SIGINT, sig_int) == SIG_ERR) {
		fprintf(stderr, "can't set signal handler: %s\n", strerror(errno));
		goto cleanup;
	}

	printf("Successfully started! Please run `sudo cat /sys/kernel/debug/tracing/trace_pipe` "
	       "to see output of the BPF programs.\n");

	while (!stop) {
		fprintf(stderr, ".");
		sleep(1);
	}

cleanup:
	kprobe_bpf__destroy(skel);
	return -err;
}

内核5.5引入了BPF trampoline，可以让内核和BPF程序更快速的相互调用。fentry/fexit是它的一个用例，fentry/fexit基本上等价于kprobe/kretprobe，但是调用BPF程序不会引起额外的overhead。

在XDP开发中BPF trampoline能很大程度上改善BPF相关的网络troubleshooting的体验。BPF trampoline支持将fentry/fexit BPF程序挂钩到任何网络BPF程序上，从而可以看到任何XDP/TC/lwt/cgroup程序的输入输出封包，同时不会产生干扰。

libbpf-bootstrap提供了一个fentry样例，类似于kprobe样例，它也是挂钩到do_unlinkat()函数，从而在文件被删除后触发BPF程序，记录各种信息。

fentry/fexit提升了性能的同时，也改善了开发体验。访问指针参数时，不再需要调用助手函数，可以直接解引用。fexit和kretprobe比起来，可以同时返回输入参数和返回值，后者只能访问返回值。

内核空间代码：

#include "vmlinux.h"
#include <bpf/bpf_helpers.h>
#include <bpf/bpf_tracing.h>

char LICENSE[] SEC("license") = "Dual BSD/GPL";

// 注解里必须包含目标内核函数的名字
SEC("fentry/do_unlinkat")
int BPF_PROG(do_unlinkat, int dfd, struct filename *name)
{
	pid_t pid;

	pid = bpf_get_current_pid_tgid() >> 32;
	bpf_printk("fentry: pid = %d, filename = %s\n", pid, name->name);
	return 0;
}

SEC("fexit/do_unlinkat")
//                             可以同时访问入参和返回值
int BPF_PROG(do_unlinkat_exit, int dfd, struct filename *name, long ret)
{
	pid_t pid;

	pid = bpf_get_current_pid_tgid() >> 32;
	bpf_printk("fexit: pid = %d, filename = %s, ret = %ld\n", pid, name->name, ret);
	return 0;
}

用户空间代码：

#include <stdio.h>
#include <unistd.h>
#include <signal.h>
#include <string.h>
#include <errno.h>
#include <sys/resource.h>
#include <bpf/libbpf.h>
#include "fentry.skel.h"

static volatile sig_atomic_t stop;

int main(int argc, char **argv)
{
	struct fentry_bpf *skel;
	int err;

	// 注册日志回调钩子、调整rlimit、打开并加载BPF程序

	// 挂钩
	err = fentry_bpf__attach(skel);
	if (err) {
		fprintf(stderr, "Failed to attach BPF skeleton\n");
		goto cleanup;
	}

	while (!stop) {
		fprintf(stderr, ".");
		sleep(1);
	}

cleanup:
	fentry_bpf__destroy(skel);
	return -err;
}

内核在samples/bpf/下包含了若干eBPF程序示例。这些程序都包含两部分：

1. *_kern.c

   会编译为BPF内核程序

2. *_user.c

   为用户空间程序，加载上述内核程序

这些样例没有封装，直接使用libbpf提供的函数完成各种功能，包括助手函数调用、ELF加载、BPF挂钩、Map创建和读写。

执行下面的命令构建示例：

# 可能需要进行必要的清理
make -C tools clean
make -C samples/bpf clean
make clean

# 当前正在构建版本的内核头文件，复制到usr/include子目录。构建samples会优先使用这些头文件
make headers_install

# 构建BPF样例
make M=samples/bpf

eBPF程序代码：

#include <linux/ptrace.h>
#include <linux/version.h>
#include <uapi/linux/bpf.h>
#include <bpf/bpf_helpers.h>
#include <bpf/bpf_tracing.h>

struct pair {
	u64 val;
	u64 ip;
};

// 定义一个Map
struct {
    // eBPF提供多种Map，BPF_MAP_TYPE_HASH是其中之一
	__uint(type, BPF_MAP_TYPE_HASH);
	// 键值的类型
	__type(key, long);
	__type(value, struct pair);
	// 容量
	__uint(max_entries, 1000000);
} my_map SEC(".maps");
        // SEC宏用于在二进制文件中创建一个新的段

// 这个段实际上声明了挂钩点
SEC("kprobe/kmem_cache_free")
// 从Map中删除一个键值
int bpf_prog1(struct pt_regs *ctx)
{
	long ptr = PT_REGS_PARM2(ctx);

	bpf_map_delete_elem(&my_map, &ptr);
	return 0;
}

// 这个段实际上声明了挂钩点
SEC("kretprobe/kmem_cache_alloc_node")
// 添加一个键值到Map
int bpf_prog2(struct pt_regs *ctx)
{
	long ptr = PT_REGS_RC(ctx);
	long ip = 0;

	/* get ip address of kmem_cache_alloc_node() caller */
	BPF_KRETPROBE_READ_RET_IP(ip, ctx);

	struct pair v = {
		.val = bpf_ktime_get_ns(),
		.ip = ip,
	};

	bpf_map_update_elem(&my_map, &ptr, &v, BPF_ANY);
	return 0;
}
char _license[] SEC("license") = "GPL";
u32 _version SEC("version") = LINUX_VERSION_CODE;

用于空间程序源码：

#include <stdio.h>
#include <stdlib.h>
#include <signal.h>
#include <unistd.h>
#include <stdbool.h>
#include <string.h>
#include <time.h>
#include <sys/resource.h>

#include <bpf/bpf.h>
#include <bpf/libbpf.h>

struct pair {
	long long val;
	__u64 ip;
};

static __u64 time_get_ns(void)
{
	struct timespec ts;

	clock_gettime(CLOCK_MONOTONIC, &ts);
	return ts.tv_sec * 1000000000ull + ts.tv_nsec;
}

static void print_old_objects(int fd)
{
	long long val = time_get_ns();
	__u64 key, next_key;
	struct pair v;

	key = write(1, "\e[1;1H\e[2J", 12); /* clear screen */

	key = -1;
	while (bpf_map_get_next_key(fd, &key, &next_key) == 0) {
		bpf_map_lookup_elem(fd, &next_key, &v);
		key = next_key;
		if (val - v.val < 1000000000ll)
			/* object was allocated more then 1 sec ago */
			continue;
		printf("obj 0x%llx is %2lldsec old was allocated at ip %llx\n",
		       next_key, (val - v.val) / 1000000000ll, v.ip);
	}
}

int main(int ac, char **argv)
{
	struct rlimit r = {RLIM_INFINITY, RLIM_INFINITY};
	struct bpf_link *links[2];
	struct bpf_program *prog;
	struct bpf_object *obj;
	char filename[256];
	int map_fd, i, j = 0;

	if (setrlimit(RLIMIT_MEMLOCK, &r)) {
		perror("setrlimit(RLIMIT_MEMLOCK, RLIM_INFINITY)");
		return 1;
	}

	snprintf(filename, sizeof(filename), "%s_kern.o", argv[0]);
	// 打开编译好的eBPF程序，tracex4_kern.o
	obj = bpf_object__open_file(filename, NULL);
	if (libbpf_get_error(obj)) {
		fprintf(stderr, "ERROR: opening BPF object file failed\n");
		return 0;
	}

	// 载入eBPF程序
	// 调用之后，定义在eBPF中的探针被添加到/sys/kernel/debug/tracing/kprobe_events
	//   cat /sys/kernel/debug/tracing/kprobe_events
	//   p:kprobes/kmem_cache_free kmem_cache_free
	//   r:kprobes/kmem_cache_alloc_node kmem_cache_alloc_node
	if (bpf_object__load(obj)) {
		fprintf(stderr, "ERROR: loading BPF object file failed\n");
		goto cleanup;
	}

	// 找到共享的Map
	map_fd = bpf_object__find_map_fd_by_name(obj, "my_map");
	if (map_fd < 0) {
		fprintf(stderr, "ERROR: finding a map in obj file failed\n");
		goto cleanup;
	}

	// 执行挂钩
	bpf_object__for_each_program(prog, obj) {
		links[j] = bpf_program__attach(prog);
		if (libbpf_get_error(links[j])) {
			fprintf(stderr, "ERROR: bpf_program__attach failed\n");
			links[j] = NULL;
			// 如果出错，解除所有已经注册的钩子
			goto cleanup;
		}
		j++;
	}

	// 读取Map并打印
	for (i = 0; ; i++) {
		print_old_objects(map_fd);
		sleep(1);
	}

cleanup:
	for (j--; j >= 0; j--)
		bpf_link__destroy(links[j]);

	bpf_object__close(obj);
	return 0;
}

这个简单的、可以和iproute2一起工作的XDP样例，判断封包是否是IPv6的，如果是，则丢弃：

#define KBUILD_MODNAME "xdp_ipv6_filter"
#include <uapi/linux/bpf.h>
#include <uapi/linux/if_ether.h>
#include <uapi/linux/if_packet.h>
#include <uapi/linux/if_vlan.h>
#include <uapi/linux/ip.h>
#include <uapi/linux/in.h>
#include <uapi/linux/tcp.h>
#include "bpf_helpers.h"

#define DEBUG 1

#ifdef  DEBUG
/* Only use this for debug output. Notice output from  bpf_trace_printk()
 * end-up in /sys/kernel/debug/tracing/trace_pipe
 */
#define bpf_debug(fmt, ...)                     \
        ({                          \
            char ____fmt[] = fmt;               \
            // 这个函数打印消息到 /sys/kernel/debug/tracing/trace_pipe
            bpf_trace_printk(____fmt, sizeof(____fmt),  \
                     ##__VA_ARGS__);            \
        })
#else
#define bpf_debug(fmt, ...) { } while (0)
#endif

// 解析包头得到ethertype
static __always_inline bool parse_eth(struct ethhdr *eth, void *data_end, u16 *eth_type)
{
    u64 offset;

    offset = sizeof(*eth);
    if ((void *)eth + offset > data_end)
        return false;
    *eth_type = eth->h_proto;
    return true;
}

// 定义一个名为prog的段
// 由于我们使用iproute2来挂钩，因此必须用prog这个段名。否则iproute2无法识别
SEC("prog")
// xdp_md结构包含访问封包所需的所有数据
int xdp_ipv6_filter_program(struct xdp_md *ctx)
{
    // 得到封包头尾指针
    void *data_end = (void *)(long)ctx->data_end;
    void *data     = (void *)(long)ctx->data;
    struct ethhdr *eth = data;
    u16 eth_type = 0;
    // 调用parse_eth函数，可以获取封包的ethertype
    if (!(parse_eth(eth, data_end, eth_type))) {
        bpf_debug("Debug: Cannot parse L2\n");
        return XDP_PASS;
    }

    bpf_debug("Debug: eth_type:0x%x\n", ntohs(eth_type));
    // 判断ethertype是否IPv6
    if (eth_type == ntohs(0x86dd)) {
        return XDP_PASS;
    } else {
        return XDP_DROP;
    }
}

char _license[] SEC("license") = "GPL";

编译此程序后得到xdp_ipv6_filter.o文件。要将此文件加载到网络接口，可以使用两种方法：

1. 编写一个用户空间程序，加载对象文件，挂钩到一个网络接口
2. 调用iproute2进行等价操作

某些网络接口在驱动层支持XDP，包括ixgbe, i40e, mlx5, veth, tap, tun, virtio_net等。这种情况下，XDP钩子实现在网络栈的最底部，即NIC从Rx Ring中接收到封包之后，具有最好的性能。对于其它类型的网络接口，XDP钩子则在更高的层次实现，性能相对较差。

我们这里用一对veth来测试：

sudo ip link add dev veth0 type veth peer name veth1
sudo ip link set up dev veth0
sudo ip link set up dev veth1

# 挂钩eBPF程序到接口上，程序必须写在prog段中
sudo ip link set dev veth1 xdp object xdp_ipv6_filter.o

# 查看接口信息
sudo ip link show veth1
8: veth1@veth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 xdp qdisc noqueue state UP mode DEFAULT group default qlen 1000
    link/ether 32:05:fc:9a:d8:75 brd ff:ff:ff:ff:ff:ff
    # 可以看到xdp标记
    prog/xdp id 32 tag bdb81fb6a5cf3154 jited

为了验证eBPF程序能正常工作，我们通过tcpdump回放一段录制的封包：

# 在veth1上录制IPv6封包，如果程序正常工作，应该接收不到
sudo tcpdump "ip6" -i veth1 -w captured.pcap -c 10
tcpdump: listening on veth1, link-type EN10MB (Ethernet), capture size 262144 bytes
# 预期结果：
# 10 packets captured
# 10 packets received by filter
# 0 packets dropped by kernel


# 将IPv4/IPv6混合流量（此pcap中包含10个IPv4，10个IPv6）回放到veth0
# q由于eBPF程序的存在IPv6的封包应该不会发到veth1
sudo tcpreplay -i veth0 ipv4-and-ipv6-data.pcap

在/sys/kernel/debug/tracing/trace_pipe 中可以看到日志：

sudo cat /sys/kernel/debug/tracing/trace_pipe
tcpreplay-4496  [003] ..s1 15472.046835: 0: Debug: eth_type:0x86dd
tcpreplay-4496  [003] ..s1 15472.046847: 0: Debug: eth_type:0x86dd
tcpreplay-4496  [003] ..s1 15472.046855: 0: Debug: eth_type:0x86dd
tcpreplay-4496  [003] ..s1 15472.046862: 0: Debug: eth_type:0x86dd
tcpreplay-4496  [003] ..s1 15472.046869: 0: Debug: eth_type:0x86dd
tcpreplay-4496  [003] ..s1 15472.046878: 0: Debug: eth_type:0x800
tcpreplay-4496  [003] ..s1 15472.046885: 0: Debug: eth_type:0x800
tcpreplay-4496  [003] ..s1 15472.046892: 0: Debug: eth_type:0x800
tcpreplay-4496  [003] ..s1 15472.046903: 0: Debug: eth_type:0x800
tcpreplay-4496  [003] ..s1 15472.046911: 0: Debug: eth_type:0x800
...

BCC提供了开发可移植的BPF程序的一套方法，但是比起新出现的BPF CO-RE有不少缺点，建议切换为BPF CO-RE。

如果你需要同时支持BCC和CO-RE，可以利用

BCC_SEC

#ifdef BCC_SEC
#define __BCC__
#endif

#ifdef __BCC__
/* BCC-specific code */
#else
/* libbpf-specific code */
#endif

使用BPF CO-RE时，你不需要包含任何内核头文件（

#include <linux/whatever.h>

vmlinux.h

#ifdef __BCC__
/* linux headers needed for BCC only */
#else /* __BCC__ */
#include "vmlinux.h"               /* all kernel types */
#include <bpf/bpf_helpers.h>       /* most used helpers: SEC, __always_inline, etc */
#include <bpf/bpf_core_read.h>     /* for BPF CO-RE helpers */
#include <bpf/bpf_tracing.h>       /* for getting kprobe arguments */
#endif /* __BCC__ */

由于vmlinux.h中可能缺少一部分内核通过#define定义的常量，因此你可能需要重新声明他们，这些变量中最常用的，已经声明在

bpf_helpers.h

BCC会自动将

tsk->parent->pid

bpf_core_read.h

BPF_CORE_READ(tsk, parent, pid)

从5.5+开始，

tp_btf

fentry

fext

BPF_CORE_READ

下面给出BCC和libbpf声明Map语法的对比：

/* Array */
#ifdef __BCC__
BPF_ARRAY(my_array_map, struct my_value, 128);
#else
struct {
    __uint(type, BPF_MAP_TYPE_ARRAY);
    __uint(max_entries, 128);
    __type(key, u32);
    __type(value, struct my_value);
} my_array_map SEC(".maps");
#endif

/* Hashmap */
#ifdef __BCC__
BPF_HASH(my_hash_map, u32, struct my_value);
#else
struct {
    __uint(type, BPF_MAP_TYPE_HASH);
    __uint(max_entries, 10240);
    __type(key, u32);
    __type(value, struct my_value);
} my_hash_map SEC(".maps")
#endif

/* per-CPU array */
#ifdef __BCC__
BPF_PERCPU_ARRAY(heap, struct my_value, 1);
#else
struct {
    __uint(type, BPF_MAP_TYPE_PERCPU_ARRAY);
    __uint(max_entries, 1);
    __type(key, u32);
    __type(value, struct my_value);
} heap SEC(".maps");
#endif

注意：BCC中的Map默认大小一般是10240，使用libbpf时则需要精确的设置。

PERF_EVENT_ARRAY、STACK_TRACE以及一些其它的特殊Map（DEVMAP、CPUMAP）尚不支持BTF类型的键值，需要直接指定key_size/value_siz：

/* Perf event array (for use with perf_buffer API) */
#ifdef __BCC__
BPF_PERF_OUTPUT(events);
#else
struct {
    __uint(type, BPF_MAP_TYPE_PERF_EVENT_ARRAY);
    __uint(key_size, sizeof(u32));
    __uint(value_size, sizeof(u32));
} events SEC(".maps");
#endif

BCC使用伪C++风格的语法，这些语法会自动被改写为BPF助手函数调用。使用CO-RE时候，你需要将：

some_map.operation(some, args)

改写为：

bpf_map_operation_elem(&some_map, some, args);

下面是一些例子：

#ifdef __BCC__
    struct event *data = heap.lookup(&zero);
#else
    struct event *data = bpf_map_lookup_elem(&heap, &zero);
#endif

#ifdef __BCC__
    my_hash_map.update(&id, my_val);
#else
    bpf_map_update_elem(&my_hash_map, &id, &my_val, 0 /* flags */);
#endif

#ifdef __BCC__
    events.perf_submit(args, data, data_len);
#else
    bpf_perf_event_output(args, &events, BPF_F_CURRENT_CPU, data, data_len);
#endif

使用CO-RE时必须用

SEC()

#if !defined(__BCC__)
SEC("tracepoint/sched/sched_process_exec")
#endif
int tracepoint__sched__sched_process_exec(
#ifdef __BCC__
    struct tracepoint__sched__sched_process_exec *args
#else
    struct trace_event_raw_sched_process_exec *args
#endif
) {
/* ... */
}

常用的约定例如：

tp/<category>/<name>

kprobe/<func_name>

kretprobe/<func_name>

raw_tp/<name>

cgroup_skb/ingress

cgroup_skb/egress

cgroup/<subtype>

BCC和libbpf关于tracepoint上下文类型的命名有所不同。BCC的格式是

tracepoint__<category>__<name>

libbpf则没有这种自动生成类型的能力，不过内核已经提供了类似的，包含了所有tracepoint数据的类型，其命名为

trace_event_raw_<name>

某些内核中的tracepoint会复用公共类型，因此上述类型对应关系不一定可用。例如没有

trace_event_raw_sched_process_exit

trace_event_raw_sched_process_template

BCC和libbpf访问tracepoint上下文大部分字段，用同样的字段名。除了一些可变长度字符串字段。BBC是

data_loc_<some_field>

__data_loc_<some_field>

Kprobe BPF程序以一个

struct pt_regs

BPF_KPROBE

BPF_KRETPROBE

#ifdef __BCC__
int kprobe__acct_collect(struct pt_regs *ctx, long exit_code, int group_dead)
#else
SEC("kprobe/acct_collect")
int BPF_KPROBE(kprobe__acct_collect, long exit_code, int group_dead)
#endif
{
    // 对于libbpf，在这里也可以访问名为ctx的pt_regs*
}

另外一个需要注意的点，在4.17+，系统调用函数发生了重命名，例如

sys_kill

__x64_sys_kill

从5.5+开始，可以考虑用

raw_tp

fentry

fexit

tracepoint

kprobe

kretprobe

在BCC代码中依赖预处理器（#ifdef 或者 #if）是流行的做法，原因通常是为了适配不同版本的内核、根据程序配置启用/禁用代码片段。CO-RE提供类似的能力：Kconfig externs和struct flavors。

参考：基于BCC进行性能追踪和网络监控

BCC（BPF Compiler Collection，BPF编译器集合）是一个工具箱，它提供了很多追踪用途的BPF程序，加载这些程序时使用BCC提供的Python接口。

一个DTrace风格的动态追踪工具，使用LLVM作为后端，将脚本编译为BPF字节码，并使用BCC和内核的BPF tracing基础设施进行交互。和原生BCC相比，它提供了更加高级的、用于实现追踪脚本的语言。

参考：利用perf剖析Linux应用程序

perf_events是内核2.6+的一部分，用户空间工具perf在包linux-tools-common中。它有三种工作模式，其中最新的是4.4引入的BPF模式，支持载入tracing BPF程序。

1. Dive into BPF: a list of reading material
2. https://docs.cilium.io/en/v1.9/bpf
3. list of eBPF helper functions

The post eBPF学习笔记 appeared first on 绿色记忆.

在一个启用了IPVS模式kube-proxy的K8S集群中，运行着一个Docker Registry服务。我们尝试通过docker manifest命令（带上--insecure参数）来推送manifest时，出现TLS timeout错误。

这个Registry通过ClusterIP类型的Service暴露访问端点，且仅仅配置了HTTP/80端口。docker manifest命令的--insecure参数的含义是，在Registry不支持HTTPS的情况下，允许使用不安全的HTTP协议通信。从报错上来看，很明显docker manifest认为Registry支持HTTPS协议。

在宿主机上尝试

telnet RegistryClusterIP 443

如果kube-proxy启用了IPVS模式，并且宿主机在0.0.0.0:NonServicePort上监听，那么可以在宿主机上、或者Pod内，通过任意ClusterIP:NonServicePort访问到宿主机的NonServicePort。

这一行为显然不符合预期，我们期望仅仅在Service对象中声明的端口，才可能通过Cluster连通。如果ClusterIP上的未知端口，内核应该丢弃报文或者返回适当的ICMP。

如果kube-proxy使用iptables模式，不会出现这种异常行为。

启用IPVS的情况下，所有ClusterIP都会绑定在kube-ipvs0这个虚拟的网络接口上。例如对于kube-dns服务的ClusterIP 10.96.0.10（ServicePort为TCP 53 / TCP 9153）：

5: kube-ipvs0: <BROADCAST,NOARP> mtu 1500 qdisc noop state DOWN group default 
    link/ether fa:d9:9e:37:12:68 brd ff:ff:ff:ff:ff:ff
    inet 10.96.0.10/32 brd 10.96.0.10 scope global kube-ipvs0
       valid_lft forever preferred_lft forever

这种绑定是必须的，因为IPVS的工作原理是，在netfilter挂载点LOCAL_IN上注册钩子ip_vs_in，拦截目的地是VIP（ClusterIP）的封包。而要使得封包进入到LOCAL_IN，它的目的地址必须是本机地址。

每当为网络接口添加一个IP地址，内核都会自动在local路由表中增加一条规则，对于上面的10.96.0.10，会增加：

# 对于目的地址是10.96.0.10的封包，从kube-ipvs0发出，如果没有指定源IP，使用10.96.0.10
local 10.96.0.10 dev kube-ipvs0 proto kernel scope host src 10.96.0.10

上述自动添加路由的一个副作用是，对于任意一个端口Port，如果不存在匹配ClusterIP:Port的IPVS规则，同时宿主机上某个应用在0.0.0.0:Port上监听，封包就会交由此应用处理。

在宿主机上执行

telnet 10.96.0.10 22

1. 出站选路，根据local表路由规则，从kube-ipvs0接口发出封包
2. 由于kube-ipvs0是dummy的，封包立刻从kube-ipvs0的出站队列移动到入站队列
3. 目的地址是本地地址，因此进入LOCAL_IN挂载点
4. 由于22不是ServicePort，封包被转发给本地进程处理，即监听了22的那个进程

如果删除内核自动在local表中添加的路由：

ip route del table local local 10.96.0.10 dev kube-ipvs0 proto kernel scope host src 10.96.0.10

则会出现以下现象：

1. 无法访问10.96.0.10:22。这是我们期望的，因为10.96.0.10这个服务没有暴露22端口，此端口理当不通
2. 无法ping 10.96.0.10。这不是我们期望的，但是一般情况下不会有什么问题。iptables模式下ClusterIP就是无法ping的，IPVS模式下可以在本机ping仅仅是绑定ClusterIP到kube-ipvs0的一个副作用。通常应用程序不应该对ClusterIP做ICMP检测，来判断服务是否可用，因为这依赖了kube-proxy的特定工作模式
3. 在宿主机上，可以访问10.96.0.10:53。这是我们期望的，宿主机上可以访问ClusterIP
4. 在某个容器的网络命名空间下，无法访问10.96.0.10:53。这不是我们期望的，相当于Pod无法访问ClusterIP了

以上4条，惟独3难以理解。为什么路由没了，宿主机仍然能访问ClusterIP:ServicePort？这个我们还没有从源码级别深究，但是很明显和IPVS有关。IPVS在LOCAL_OUT上挂有钩子，它可能在此钩子中检测到来自本机（主网络命名空间）的、访问ClusterIP+ServicePort（即IPVS虚拟服务）的封包，并进行了某种“魔法”处理，从而避开了没有路由的问题。

下面我们进一步验证上述“魔法”处理的可能性。使用

tcpdump -i any host 10.96.0.10

#                  容器IP
11:32:00.448470 IP 172.27.0.24.56378 > 10.96.0.10.53: Flags [S], seq 2946888109, win 28200, options...

但是从宿主机访问ClusterIP:ServicePort时，则捕获不到任何流量。但是，通过iptables logging，我们可以确定，内核的确以ClusterIP为源地址和目的地址，发起了封包：

iptables -t mangle -I OUTPUT 1 -p tcp --dport 53 -j LOG --log-prefix 'out-d53: '

# dmesg -w
#                                      源地址          目的地址
# [3374381.426541] out-d53: IN= OUT=lo SRC=10.96.0.100 DST=10.96.0.100 LEN=52 TOS=0x10 PREC=0x00 TTL=64 ID=18885 DF PROTO=TCP SPT=42442 DPT=53 WINDOW=86 RES=0x00 ACK URGP=0 

回顾一下数据报出站、入站的处理过程：

1. 出站，依次经过 netfilter/iptables ⇨ tcpdump ⇨ 网络接口 ⇨网线
2. 入站，依次经过 网线 ⇨ 网络接口 ⇨ tcpdump ⇨ netfilter/iptables

只有当IPVS在宿主机请求10.96.0.10的封包出站时，在netfilter中对匹配IPVS虚拟服务的封包进行如下处理，才能解释iptables中能看到10.96.0.10，而紧随其后的tcpdump中却又看不到的现象：

1. 修改目的地址为Service的Endpoint地址，这就是NAT模式的IPVS（即kube-proxy使用NAT模式）应有的行为
2. 修改了源地址为当前宿主机的地址，不这样做，回程报文就无法路由回来

另外注意一下，如果从宿主机访问ClusterIP:NonServicePort，则tcpdump能捕获到源或目的地址为ClusterIP的流量。这是因为IPVS发现它不匹配任何虚拟服务，会直接返回NF_ACCEPT，然后封包就按照常规流程处理了。

如果宿主机上有一个在0.0.0.0上监听的、存在安全漏洞的服务，则可能被恶意的工作负载利用。

少部分的应用程序，例如docker manifest，其行为取决于端口探测的结果，会无法正常工作。

可能的解决方案有：

1. 在iptables中匹配哪些针对ClusterIP:NonServicePort的流量，Drop或Reject掉
2. 使用基于fwmark的IPVS虚拟服务，这需要在iptables中对针对ClusterIP:ServicePort的流量打fwmark，而且每个ClusterIP都需要占用独立的fwmark，难以管理

对于解决方案1，可以使用如下iptables规则： 

#                 如果目的地址是ClusterIP    但是目的端口不是ServicePort           则拒绝
iptables -A INPUT -d  10.96.0.0/12 -m set ! --match-set KUBE-CLUSTER-IP dst,dst -j REJECT

这个规则能够为容器解决宿主机端口泄露的问题，但是会导致宿主机上无法访问ClusterIP。

引起此问题的原因是，在宿主机访问ClusterIP时，会同时使用ClusterIP作为源地址/目的地址。这样，来自Endpoint的回程报文，unNATed后的目的地址，就会匹配到上面的iptables规则，从而导致封包被Reject掉。

要解决此问题，我们可以修改内核自动添加的路由，提示使用其它地址作为源地址：

# 这条路由给出src提示，当访问10.96.0.10时，选取192.168.104.82（节点IP）作为源地址
ip route replace table local local 10.96.0.10 dev kube-ipvs0 proto kernel scope host src 192.168.104.82

上文我们提到了一个“魔法”处理的猜想，这里我们对IPVS的实现细节进行深入学习，证实此猜想。

本节牵涉到的内核源码均来自linux-3.10.y分支。

这是从2.4.x引入内核的一个框架，用于实现防火墙、NAT、封包修改、记录封包日志、用户空间封包排队之类的功能。

netfilter运行在内核中，允许内核模块在Linux网络栈的不同位置注册钩子（回调函数），当每个封包穿过网络栈时，这些钩子函数会被调用。

iptables是经典的，基于netfilter的用户空间工具。它的继任者是nftables，它更加灵活、可扩容、性能好。

netfilter提供了5套钩子（的挂载点）：

int ip_rcv(struct sk_buff *skb, struct net_device *dev, struct packet_type *pt, struct net_device *orig_dev)
{
	// ...
	return NF_HOOK(NFPROTO_IPV4, NF_INET_PRE_ROUTING, skb, dev, NULL,
		       ip_rcv_finish);
}

这些挂载点，和iptables的各链是对应的。

要在内核中使用netfilter的钩子，你需要调用函数：

// 注册钩子
int nf_register_hook(struct nf_hook_ops *reg){}
// 反注册钩子
void nf_unregister_hook(struct nf_hook_ops *reg){}

入参nf_hook_ops是一个结构：

struct nf_hook_ops {
	// 钩子的函数指针，依据内核的版本不同此函数的签名有所差异
	nf_hookfn		*hook;
	struct net_device	*dev;
	void			*priv;
	// 钩子针对的协议族，PF_INET表示IPv4
	u_int8_t		pf;
	// 钩子类型代码，参考上面的表格
	unsigned int		hooknum;
	// 每种类型的钩子，都可以有多个，此数字决定执行优先级
	int			priority;
};


// 钩子函数的签名
typedef unsigned int nf_hookfn(unsigned int hooknum,
			       struct sk_buff *skb, // 正被处理的数据报
			       const struct net_device *in, // 输入设备
			       const struct net_device *out, // 是出设备
			       int (*okfn)(struct sk_buff *)); // 如果通过钩子检查，则调用此函数，通常用不到

/* Responses from hook functions. */
// 丢弃该报文，不再继续传输或处理
#define NF_DROP 0
// 继续正常传输报文，如果后面由低优先级的钩子，仍然会调用它们
#define NF_ACCEPT 1
// 告知netfilter，报文被别人偷走处理了，不需要再对它做任何处理
// 下文的分析中，我们有个例子。一个netfilter钩子在内部触发了对netfilter钩子的调用
// 外层钩子返回的就是NF_STOLEN，相当于将封包的控制器转交给内层钩子了
#define NF_STOLEN 2
// 对该数据报进行排队，通常用于将数据报提交给用户空间进程处理
#define NF_QUEUE 3
// 再次调用该钩子函数
#define NF_REPEAT 4
// 继续正常传输报文，不会调用此挂载点的后续钩子
#define NF_STOP 5
#define NF_MAX_VERDICT NF_STOP 

优先级通常以下面的枚举为基准+/-：

enum nf_ip_hook_priorities {
	// 数值越小，优先级越高，越先执行
	NF_IP_PRI_FIRST = INT_MIN,
	NF_IP_PRI_CONNTRACK_DEFRAG = -400,
	// 可以看到iptables各表注册的钩子的优先级
	NF_IP_PRI_RAW = -300,
	NF_IP_PRI_SELINUX_FIRST = -225,
	NF_IP_PRI_CONNTRACK = -200,
	NF_IP_PRI_MANGLE = -150,
	NF_IP_PRI_NAT_DST = -100,
	NF_IP_PRI_FILTER = 0,
	NF_IP_PRI_SECURITY = 50,
	NF_IP_PRI_NAT_SRC = 100,
	NF_IP_PRI_SELINUX_LAST = 225,
	NF_IP_PRI_CONNTRACK_HELPER = 300,
	NF_IP_PRI_CONNTRACK_CONFIRM = INT_MAX,
	NF_IP_PRI_LAST = INT_MAX,
};

 ip_vs模块初始化时，会通过ip_vs_init函数，调用nf_register_hook，注册以下netfilter钩子：

static struct nf_hook_ops ip_vs_ops[] __read_mostly = {
	// 注册到LOCAL_IN，这两个钩子处理外部客户端的报文
	// 转而调用ip_vs_out，用于NAT模式下，处理LVS回复外部客户端的报文，例如修改IP地址
	{
		.hook		= ip_vs_reply4,
		.owner		= THIS_MODULE,
		.pf		= NFPROTO_IPV4,
		.hooknum	= NF_INET_LOCAL_IN,
		.priority	= NF_IP_PRI_NAT_SRC - 2,
	},
	// 转而调用ip_vs_in，用于处理外部客户端进入IPVS的请求报文
	// 如果没有对应请求报文的连接，则使用调度函数创建连接结构，这其中牵涉选择RS负载均衡算法
	{
		.hook		= ip_vs_remote_request4,
		.owner		= THIS_MODULE,
		.pf		= NFPROTO_IPV4,
		.hooknum	= NF_INET_LOCAL_IN,
		.priority	= NF_IP_PRI_NAT_SRC - 1,
	},

	// 注册到LOCAL_OUT，这两个钩子处理LVS本机的报文
	// 转而调用ip_vs_out，用于NAT模式下，处理LVS回复客户端的报文
	{
		.hook		= ip_vs_local_reply4,
		.owner		= THIS_MODULE,
		.pf		= NFPROTO_IPV4,
		.hooknum	= NF_INET_LOCAL_OUT,
		.priority	= NF_IP_PRI_NAT_DST + 1,
	},
	// 转而调用ip_vs_in，调度并转发（给RS）本机的请求
	{
		.hook		= ip_vs_local_request4,
		.owner		= THIS_MODULE,
		.pf		= NFPROTO_IPV4,
		.hooknum	= NF_INET_LOCAL_OUT,
		.priority	= NF_IP_PRI_NAT_DST + 2,
	},

	// 这两个函数注册到FORWARD
	// 转而调用ip_vs_in_icmp，用于处理外部客户端发到IPVS的ICMP报文，并转发到RS
	{
		.hook		= ip_vs_forward_icmp,
		.owner		= THIS_MODULE,
		.pf		= NFPROTO_IPV4,
		.hooknum	= NF_INET_FORWARD,
		.priority	= 99,
	},
	// 转而调用ip_vs_out，用于NAT模式下，修改RS给的应答报文的源地址为IPVS虚拟地址
	{
		.hook		= ip_vs_reply4,
		.owner		= THIS_MODULE,
		.pf		= NFPROTO_IPV4,
		.hooknum	= NF_INET_FORWARD,
		.priority	= 100,
	}
};

从上面的钩子我们可以看到：

1. 针对外部发起的、本机发起的，对IPVS的请求（目的是VIP的SYN），钩子的位置是不一样的：
   1. 对于外部的请求，在LOCAL_IN中处理，钩子函数为ip_vs_remote_request4
   2. 对于本机的请求，在LOCAL_OUT中处理，钩子函数为ip_vs_local_request4
2.  尽管钩子的位置不同，但是函数ip_vs_remote_request4、ip_vs_local_request4都是调用ip_vs_in。实际上，这两个函数的逻辑完全一样：
   

   /*
    *	AF_INET handler in NF_INET_LOCAL_IN chain
    *	Schedule and forward packets from remote clients
    */
   static unsigned int
   ip_vs_remote_request4(unsigned int hooknum, struct sk_buff *skb,
   		      const struct net_device *in,
   		      const struct net_device *out,
   		      int (*okfn)(struct sk_buff *))
   {
   	return ip_vs_in(hooknum, skb, AF_INET);
   }
   
   /*
    *	AF_INET handler in NF_INET_LOCAL_OUT chain
    *	Schedule and forward packets from local clients
    */
   static unsigned int
   ip_vs_local_request4(unsigned int hooknum, struct sk_buff *skb,
   		     const struct net_device *in, const struct net_device *out,
   		     int (*okfn)(struct sk_buff *))
   {
   	return ip_vs_in(hooknum, skb, AF_INET);
   }

回顾一下上文我们关于“魔法”处理的疑惑。对于从宿主机发起对10.96.0.10:53的请求，我们通过iptables logging证实了使用的源IP地址是10.96.0.10：

1. 这个请求为什么tcpdump捕获不到？
2. 为什么删除路由不影响宿主机对ClusterIP的请求（却又导致容器无法请求ClusterIP）？

这两个问题的答案，很可能就隐藏在ip_vs_in函数中，因为它是处理进入IPVS的数据报的统一入口。如果该函数同时修改了原始封包的源/目的地址，就解释了问题1；如果该函数在内部进行了选路操作，则解释了问题2。

下面分析一下ip_vs_in的代码：

static unsigned int
ip_vs_in(unsigned int hooknum, struct sk_buff *skb, int af)
{
	// 网络命名空间
	struct net *net;
	// IPVS的IP头，其中存有3层头len、协议、标记、源/目的地址
	struct ip_vs_iphdr iph;
	// 持有协议（TCP/UDP/SCTP/AH/ESP）信息，更重要的是带着很多函数指针。这些指针负责针对特定协议的IPVS逻辑
	struct ip_vs_protocol *pp;
	// 每个命名空间一个此对象，包含统计计数器、超时表
	struct ip_vs_proto_data *pd;
	// 当前封包所属的IPVS连接对象，此对象最重要的是packet_xmit函数指针。它负责将封包发走
	struct ip_vs_conn *cp;
	int ret, pkts;
	// 描述当前网络命名空间的IPVS状态
	struct netns_ipvs *ipvs;

	// 如果封包已经被标记为IPVS请求/应答，不做处理，继续netfilter常规流程
	// 后续ip_vs_nat_xmit会让封包“重入”netfilter，那时封包已经打上IPVS标记
	// 这里的判断确保重入的封包走netfilter常规流程，而不是进入死循环
	if (skb->ipvs_property)
		return NF_ACCEPT;


	// 如果封包目的地不是本机且当前不在LOCAL_OUT
	// 或者封包的dst_entry不存在，不做处理，继续netfilter常规流程
	if (unlikely((skb->pkt_type != PACKET_HOST &&
		      hooknum != NF_INET_LOCAL_OUT) ||
		     !skb_dst(skb))) {
		ip_vs_fill_iph_skb(af, skb, &iph);
		IP_VS_DBG_BUF(12, "packet type=%d proto=%d daddr=%s"
			      " ignored in hook %u\n",
			      skb->pkt_type, iph.protocol,
			      IP_VS_DBG_ADDR(af, &iph.daddr), hooknum);
		return NF_ACCEPT;
	}
	// 如果当前IPVS主机是backup，或者当前命名空间没有启用IPVS，不做处理，继续netfilter常规流程
	net = skb_net(skb);
	ipvs = net_ipvs(net);
	if (unlikely(sysctl_backup_only(ipvs) || !ipvs->enable))
		return NF_ACCEPT;

	// 使用封包的IP头填充IPVS的IP头
	ip_vs_fill_iph_skb(af, skb, &iph);

	// 如果是RAW套接字，不做处理，继续netfilter常规流程
	if (unlikely(skb->sk != NULL && hooknum == NF_INET_LOCAL_OUT &&
		     af == AF_INET)) {
		struct sock *sk = skb->sk;
		struct inet_sock *inet = inet_sk(skb->sk);

		if (inet && sk->sk_family == PF_INET && inet->nodefrag)
			return NF_ACCEPT;
	}

	// 处理ICMP报文，和我们的场景无关
	if (unlikely(iph.protocol == IPPROTO_ICMP)) {
		int related;
		int verdict = ip_vs_in_icmp(skb, &related, hooknum);
		if (related)
			return verdict;
	}

	// 如果协议不受IPVS支持，不做处理，继续netfilter常规流程
	pd = ip_vs_proto_data_get(net, iph.protocol);
	if (unlikely(!pd))
		return NF_ACCEPT;
	// 协议被支持，得到pp
	pp = pd->pp;
	// 尝试获取封包所属的IPVS连接对象
	cp = pp->conn_in_get(af, skb, &iph, 0);
	// 如果封包属于既有IPVS连接，且此连接的RS（dest）已经设置，且RS的权重为0
	// 认为是无效连接，设为过期
	if (unlikely(sysctl_expire_nodest_conn(ipvs)) && cp && cp->dest &&
	    unlikely(!atomic_read(&cp->dest->weight)) && !iph.fragoffs &&
	    is_new_conn(skb, &iph)) {
		ip_vs_conn_expire_now(cp);
		__ip_vs_conn_put(cp);
		cp = NULL;
	}

	// 调度一个新的IPVS连接，这里牵涉到RS的LB算法
	if (unlikely(!cp) && !iph.fragoffs) {
		int v;
		if (!pp->conn_schedule(af, skb, pd, &v, &cp, &iph))
			// 如果返回0，通常v是NF_DROP，这以为这调度失败，封包丢弃
			return v;
	}

	if (unlikely(!cp)) {
		IP_VS_DBG_PKT(12, af, pp, skb, 0,
			      "ip_vs_in: packet continues traversal as normal");
		if (iph.fragoffs) {
			IP_VS_DBG_RL("Unhandled frag, load nf_defrag_ipv6\n");
			IP_VS_DBG_PKT(7, af, pp, skb, 0, "unhandled fragment");
		}
		return NF_ACCEPT;
	}

	// 入站封包 —— 在我们的场景中，这是本地客户端入了IPVS系统的封包
	// 从网络栈的角度来说，我们正在处理的是出站封包...
	IP_VS_DBG_PKT(11, af, pp, skb, 0, "Incoming packet");

	// IPVS连接的RS不可用
	if (cp->dest && !(cp->dest->flags & IP_VS_DEST_F_AVAILABLE)) {
		// 立即将连接设为过期
		if (sysctl_expire_nodest_conn(ipvs)) {
			ip_vs_conn_expire_now(cp);
		}
		// 丢弃封包
		__ip_vs_conn_put(cp);
		return NF_DROP;
	}
	// 更新计数器
	ip_vs_in_stats(cp, skb);
	// 更新IPVS连接状态机，做的事情包括
	//   根据数据包 tcp 标记字段来更新当前状态机
	//   更新连接对应的统计数据，包括：活跃连接和非活跃连接
	//   根据连接状态，设置超时时间
	ip_vs_set_state(cp, IP_VS_DIR_INPUT, skb, pd);

	if (cp->packet_xmit)
		// 调用packet_xmit将封包发走，实际上是重入netfilter的LOCAL_OUT，封包控制权转移走，后续不该再操控skb
		ret = cp->packet_xmit(skb, cp, pp, &iph);
	else {
		IP_VS_DBG_RL("warning: packet_xmit is null");
		ret = NF_ACCEPT;
	}

	if (cp->flags & IP_VS_CONN_F_ONE_PACKET)
		pkts = sysctl_sync_threshold(ipvs);
	else
		pkts = atomic_add_return(1, &cp->in_pkts);

	if (ipvs->sync_state & IP_VS_STATE_MASTER)
		ip_vs_sync_conn(net, cp, pkts);

	// 放回连接对象，重置连接定时器
	ip_vs_conn_put(cp);
	return ret;
}

上面这段代码中，“魔法”处理最可能发生在：

1. conn_schedule：在这里需要进行IPVS连接的调度
2. packet_xmit：在这里发送经过IPVS处理的封包

二者都是函数指针，在TCP协议下，conn_schedule指向tcp_conn_schedule。在NAT模式下，packet_xmit指向ip_vs_nat_xmit。packet_xmit指针是在conn_schedule过程中初始化的。

我们看一下TCP协议下IPVS连接的调度过程。

static int
tcp_conn_schedule(int af, struct sk_buff *skb, struct ip_vs_proto_data *pd,
		  int *verdict, struct ip_vs_conn **cpp,
		  struct ip_vs_iphdr *iph)
{
	// 网络命名空间
	struct net *net;
	// IPVS虚拟服务对象
	struct ip_vs_service *svc;
	struct tcphdr _tcph, *th;

	// 解析L4头，如果失败，提示ip_vs_in丢弃封包
	th = skb_header_pointer(skb, iph->len, sizeof(_tcph), &_tcph);
	if (th == NULL) {
		*verdict = NF_DROP;
		return 0;
	}
	net = skb_net(skb);
	rcu_read_lock();
	if (th->syn &&
	    // 根据封包特征，去查找匹配的虚拟服务
	    (svc = ip_vs_service_find(net, af, skb->mark, iph->protocol,
				      &iph->daddr, th->dest))) {
		int ignored;
		// 如果当前网络命名空间“过载”了，丢弃封包
		if (ip_vs_todrop(net_ipvs(net))) {
			rcu_read_unlock();
			*verdict = NF_DROP;
			return 0;
		}

		// 选择一个RS，建立IPVS连接
		// 如果找不到RS，或者发生致命错误，则ignore为0或-1，这种情况下
		// IPVS连接没有成功创建，提示ip_vs_in丢弃封包，可能附带回复ICMP
		*cpp = ip_vs_schedule(svc, skb, pd, &ignored, iph);
		if (!*cpp && ignored <= 0) {
			if (!ignored)
				// ignored=0，找不到RS
				*verdict = ip_vs_leave(svc, skb, pd, iph);
			else
				*verdict = NF_DROP;
			rcu_read_unlock();
			return 0;
		}
	}
	rcu_read_unlock();
	// 如果调度成功，IPVS连接对象不为空，返回1
	/* NF_ACCEPT */
	return 1;
}

到这里我们还没有看到IPVS对封包地址进行更改，需要进一步阅读ip_vs_schedule。 

这是IPVS调度的核心函数，它支持TCP/UDP，它为虚拟服务选择一个RS，创建IPVS连接对象。

struct ip_vs_conn *
ip_vs_schedule(struct ip_vs_service *svc, struct sk_buff *skb,
	       struct ip_vs_proto_data *pd, int *ignored,
	       struct ip_vs_iphdr *iph)
{
	struct ip_vs_protocol *pp = pd->pp;
	// IPVS连接对象（connection entry）
	struct ip_vs_conn *cp = NULL;
	struct ip_vs_scheduler *sched;
	struct ip_vs_dest *dest;
	__be16 _ports[2], *pptr;
	unsigned int flags;

	// ...

	*ignored = 0;

	/*
	 *    Non-persistent service
	 */
	// 调度工作委托给虚拟服务的scheduler
	sched = rcu_dereference(svc->scheduler);
	// 调度器就是选择一个RS（ip_vs_dest）
	dest = sched->schedule(svc, skb);
	if (dest == NULL) {
		IP_VS_DBG(1, "Schedule: no dest found.\n");
		return NULL;
	}

	flags = (svc->flags & IP_VS_SVC_F_ONEPACKET
		 && iph->protocol == IPPROTO_UDP) ?
		IP_VS_CONN_F_ONE_PACKET : 0;

	// 初始化IPVS连接对象 ip_vs_conn
	{
		struct ip_vs_conn_param p;

		ip_vs_conn_fill_param(svc->net, svc->af, iph->protocol,
				      &iph->saddr, pptr[0], &iph->daddr,
				      pptr[1], &p);
		// 操控ip_vs_conn的逻辑包括：
		//   初始化定时器
		//   设置网络命名空间
		//   设置地址、fwmark、端口
		//   根据IP版本、IPVS模式（NAT/DR/TUN）为连接设置一个packet_xmit
		cp = ip_vs_conn_new(&p, &dest->addr,
				    dest->port ? dest->port : pptr[1],
				    flags, dest, skb->mark);
		if (!cp) {
			*ignored = -1;
			return NULL;
		}
	}

	// ...
	return cp;
}

到这里我们可以看到， conn_schedule仍然没有对封包做任何修改。看来关键在packet_xmit函数中。

int ip_vs_nat_xmit(struct sk_buff *skb, struct ip_vs_conn *cp,
	       struct ip_vs_protocol *pp, struct ip_vs_iphdr *ipvsh)
{
	// 路由表项
	struct rtable *rt;		/* Route to the other host */
	// 是否本机    是否输入路由
	int local, rc, was_input;

	EnterFunction(10);

	rcu_read_lock();
	// 是否尚未设置客户端端口
	if (unlikely(cp->flags & IP_VS_CONN_F_NO_CPORT)) {
		__be16 _pt, *p;

		p = skb_header_pointer(skb, ipvsh->len, sizeof(_pt), &_pt);
		if (p == NULL)
			goto tx_error;
		// 设置IPVS连接对象的cport
		// caddr cport 客户端地址
		// vaddr vport 虚拟服务地址
		// daddr dport RS地址
		ip_vs_conn_fill_cport(cp, *p);
		IP_VS_DBG(10, "filled cport=%d\n", ntohs(*p));
	}

	was_input = rt_is_input_route(skb_rtable(skb));
	// 出口路由查找，依据是封包、RS的地址、以及若干标识位
	// 返回值提示路由目的地是否是本机
	local = __ip_vs_get_out_rt(skb, cp->dest, cp->daddr.ip,
				   IP_VS_RT_MODE_LOCAL |
				   IP_VS_RT_MODE_NON_LOCAL |
				   IP_VS_RT_MODE_RDR, NULL);
	if (local < 0)
		goto tx_error;
	rt = skb_rtable(skb);

	// 如果目的地是本机，RS地址是环回地址，是输入
	if (local && ipv4_is_loopback(cp->daddr.ip) && was_input) {
		IP_VS_DBG_RL_PKT(1, AF_INET, pp, skb, 0, "ip_vs_nat_xmit(): "
				 "stopping DNAT to loopback address");
		goto tx_error;
	}

	// 封包将被修改，执行copy-on-write
	if (!skb_make_writable(skb, sizeof(struct iphdr)))
		goto tx_error;

	if (skb_cow(skb, rt->dst.dev->hard_header_len))
		goto tx_error;

	// 修改封包，dnat_handler指向tcp_dnat_handler
	if (pp->dnat_handler && !pp->dnat_handler(skb, pp, cp, ipvsh))
		goto tx_error;
	// 更改目的地址
	ip_hdr(skb)->daddr = cp->daddr.ip;
	// 为出站封包生成chksum
	ip_send_check(ip_hdr(skb));

	IP_VS_DBG_PKT(10, AF_INET, pp, skb, 0, "After DNAT");

	skb->local_df = 1;

	// 发送封包：
	//   如果发送出去了，返回 NF_STOLEN
	//   如果没有发送（local=1，目的地是本机），返回NF_ACCEPT
	rc = ip_vs_nat_send_or_cont(NFPROTO_IPV4, skb, cp, local);
	rcu_read_unlock();

	LeaveFunction(10);
	return rc;

  tx_error:
	kfree_skb(skb);
	rcu_read_unlock();
	LeaveFunction(10);
	return NF_STOLEN;
}

static inline int ip_vs_nat_send_or_cont(int pf, struct sk_buff *skb,  struct ip_vs_conn *cp, int local)
{
	// 注意这个NF_STOLEN的含义，参考上文
	int ret = NF_STOLEN;
	// 给封包设置IPVS标记，NF_HOOK会导致当前封包重入netfilter，此标记会让重入后的封包立即NF_ACCEPT、
	// 重入让修改后的封包有机会被ipables处理
	skb->ipvs_property = 1;
	if (likely(!(cp->flags & IP_VS_CONN_F_NFCT)))
		ip_vs_notrack(skb);
	else
		ip_vs_update_conntrack(skb, cp, 1);
	// 如果目的地不是本机
	if (!local) {
		skb_forward_csum(skb);
		// 调用LOCAL_OUT挂载点
		NF_HOOK(pf, NF_INET_LOCAL_OUT, skb, NULL, skb_dst(skb)->dev, dst_output);
	} else
		ret = NF_ACCEPT;
	return ret;
}

在ip_vs_nat_xmit中，我们可以了解到，对于宿主机发起的针对ClusterIP:ServicePort的请求

1. 封包的目的地址被修改为Endpoint（通常是Pod，IPVS中的RS）的地址
2. 修改后的封包，重新被塞入netfilter（内层），注意当前就正在netfilter（外层）中
   1. 外层钩子的返回值是NF_STOLEN：封包处理权转移给内层钩子，停止后续netfilter流程
   2. 内层钩子的返回值是NF_ACCEPT：不做IPVS相关处理，继续后续netfilter流程。IPVS前、后的LOCAL_OUT、POSTROUTING钩子都会正常执行。也就是说，对于修改后的封包，内核会进行完整、常规的netfilter处理，就像没有IPVS存在一样

到这里，我们确定了，IPVS会在LOCAL_OUT中进行DNAT。但是只有同时进行SNAT，才能解释上文的中的疑惑。

花费了不少时间在IPVS上探究后，我们意识到走错了方向。我们忘记了SANT是kube-proxy会去做的事情。查看一下iptables规则就一目了然了：

# iptables -t nat -L -n -v

Chain OUTPUT (policy ACCEPT 2 packets, 150 bytes)
 pkts bytes target     prot opt in     out     source        destination         
# 所有出站流量都要经过自定义的 KUBE-SERVICES 链
  21M 3825M KUBE-SERVICES  all  --  *  *   0.0.0.0/0         0.0.0.0/0            /* kubernetes service portals */

Chain KUBE-SERVICES (2 references)
 pkts bytes target     prot opt in     out     source        destination         
# 如果目的IP:PORT属于K8S服务，则调用KUBE-MARK-MASQ链
    0     0 KUBE-MARK-MASQ  all  --  * *  !172.27.0.0/16     0.0.0.0/0   match-set KUBE-CLUSTER-IP dst,dst

# 给封包打上标记 0x4000
Chain KUBE-MARK-MASQ (5 references)
 pkts bytes target     prot opt in     out     source         destination         
   98  5880 MARK       all  --  *       *  0.0.0.0/0          0.0.0.0/0            MARK or 0x4000

 
Chain POSTROUTING (policy ACCEPT 2 packets, 150 bytes)
 pkts bytes target     prot opt in     out     source         destination         
  44M 5256M KUBE-POSTROUTING  all  --  *  *       0.0.0.0/0   0.0.0.0/0            /* kubernetes postrouting rules */

Chain KUBE-POSTROUTING (1 references)
 pkts bytes target     prot opt in     out     source         destination         
# 仅仅处理 0x4000标记的封包
 1781  166K RETURN     all  --  *      *  0.0.0.0/0           0.0.0.0/0            mark match ! 0x4000/0x4000
# 执行SNAT     
   97  5820 MARK       all  --  *      *  0.0.0.0/0           0.0.0.0/0   MARK xor 0x4000
   97  5820 MASQUERADE  all  --  *     *  0.0.0.0/0           0.0.0.0/0   /* kubernetes service traffic requiring SNAT */

由于ip_vs_local_request4挂钩在LOCAL_OUT，优先级为NF_IP_PRI_NAT_DST+2 ，因此它是发生在上面nat表OUTPUT链中MARK之后的。也就是说在IPVS处理之前，kube-proxy已经给原始的封包打上标记。

重入的、DNAT后的封包进入LOCAL_OUT，随后进入POSTROUTING。由于标记的缘故，封包被kube-proxy的规则SNAT。

经过POSTROUTING的封包，经过tcpdump，但是由于源、目的IP地址，以及目的端口都改变了，因而我们看到tcpdump没有任何输出。

这里做一下小结。

为什么IPVS模式下，能够ping通ClusterIP？ 这是因为IPVS模式下，ClusterIP被配置为宿主机上一张虚拟网卡kube-ipvs0的IP地址。

为什么IPVS模式下，宿主机端口被ClusterIP泄漏？每当添加一个ClusterIP给网络接口后，内核自动在local表中增加一条路由，此路由保证了针对ClusterIP的访问，在没有IPVS干涉的情况下，路由到本机处理。这样，在0.0.0.0上监听的进程，就接收到报文并处理。

为什么删除内核添加的路由后：

1. 宿主机上访问ClusterIP:NonServicePort不通了？因为没有路由了
2. 没有路由了，为什么宿主机上访问ClusterIP:ServicePort仍然畅通？如上文分析，IPVS在ip_vs_nat_xmit中仍然会进行选路操作
3. 那为什么从容器网络命名空间访问ClusterIP:ServicePort不通呢？IPVS处理本地、远程客户端的代码路径不一样。容器网络命名空间是远程客户端，需要首先进入PER_ROUTING，然后选路，路由目的地是本机，才会进入LOCAL_IN，IPVS才有介入的时机。由于路由被删掉了，选路那一步就会出问题

为什么通过--match-set KUBE-CLUSTER-IP匹配目的地址，如果封包目的端口是NonServicePort则Reject：

1. 这种方案对容器命名空间有效？容器请求的源地址不会是ClusterIP，因此回程报文的目的地址不会因为匹配规则而Reject
2. 这种方案导致宿主机无法访问ClusterIP？宿主机发起请求时用的是ClusterIP，请求端口是随机的。这种请求的回程报文必然匹配规则导致Reject

The post IPVS模式下ClusterIP泄露宿主机端口的问题 appeared first on 绿色记忆.

下面这张图描述了一个L3的IP封包如何通过iptables：

 对于此图的说明：

1. Iptables和内核路由的关系：执行完PREROUTING链之后，会进行路由表的查询
2. 通过lo接口的封包，不走PREROUTING的DNAT表
3. 出站封包在OUTPUT链之前就进行了路由处理。但是如果OUTPUT进行了DNAT，则会进行重新选路
4. 入站封包，如果使用了隧道，则会经由PREROUTING - INPUT链逐层的解除隧道
5. 出站封包，如果使用了隧道，则会经由OUTPUT -POSTROUTING链逐层的进行隧道封装

下面的图示意了更接近实际的流程：

iptables是用户空间命令，通过netlink和内核的netfilter模块进行交互，在L3/L4操控封包。

netfilter是Linux网络安全大厦的基石，从2.4开始引入。它提供了一整套Hook函数机制，IP层的5个钩子点对应了iptables的5个内置链条：

1. PREROUTING，在此DNAT
2. POSTROUTING，在此SNAT
3. INPUT，处理输入给本地进程的封包
4. OUTPUT，处理本地进程输出的封包
5. FORWARD，处理转发给其他机器、其他网络命名空间的封包

对于从网络接口入站的IP封包，首先进入PREROUTING链，然后进行路由判断：

1. 如果封包路由目的地是本机，则进入INPUT链，然后发给本地进程
2. 如果封包路由目的地不是本机，并且启用了IP转发，则进入FORWARD链，然后通过POSTROUTING链，最后经过网络接口发走

对于本地进程发往协议栈的封包，则首先通过OUTPUT链，然后通过POSTROUTING链，最后经过网络接口发走

除了链条，iptables还包含一个正交的概念，表是用于分类管理iptables规则的。不同的表，通常用作不同的目的：

1. filter表：用于控制到达某条链条上的数据包如何处理，是放行（Accept）、丢弃（Drop）还是拒绝（Reject）。如果不指定-t参数，这是默认操控的表格
2. nat表：用于修改源地址，或者目的地址。该表格在某个创建了新连接的封包出现时生效
3. mangle表：该表格用于修改封包的内容
4. raw表：具有高优先级，可以对接收到的封包在连接跟踪（Connection Tracking，为了支持NAT，iptables会对每个L4连接进行跟踪，也就是维护每个L4连接的状态）前进行处理（也就是取消跟踪），可以应用在那些不需要做NAT的情况下提高性能。例如高访问的Web服务，可以不让iptables做80端口封包的连接跟踪
5. security表：用于强制访问控制（Mandatory Access Control），很少使用

表的优先级从高到低为 raw ⇨ mangle ⇨ nat ⇨ filter ⇨ security。用户不能自定义新表。

封包会依次经过相关的链，在每个链中，会根据表的优先级，依次遍历各个表中的规则。任何表中的规则都有机会拒绝封包。

需要注意，不是任何链条上可以挂任何表：

1. raw可以挂在PREROUTING、OUTPUT
2. mangle可以挂在任何链上
3. nat（SNAT）可以挂在POSTROUTING、INPUT
4. nat（DNAT）可以挂在PREROUTING、OUTPUT
5. filter可以挂在FORWARD、INPUT、OUTPUT
6. security可以挂在FORWARD、INPUT、OUTPUT

用于修改封包。某些目标只能用在mangle表中，包括：

1. TOS，此目标设置封包的Type Of Servier字段，以便影响封包的处理策略，例如如何进行路由
2. TTL，设置封包的Time To Live字段
3. MARK，给封包添加一个标记值（数字），iproute2能够识别此mark并且进行特殊的路由处理。此外基于MARK还可以进行带宽限制、基于Class的排队

应当仅仅用于网络地址转换。也就是使用以下目标：

1. DNAT：用在你有一个公共地址，别人访问此地址时，你需要将访问重定向到防火墙背后的某个服务时
2. SNAT：允许隐藏在防火墙背后的内网机器访问外部网络
3. MASQUERADE：类似SNAT，不同之处在于每次都需要动态计算使用什么作为转换后的源地址。用在主机地址不固定的情况下
4. REDIRECT：类似于DNAT，但是新的目的地址被锁定为接收封包的那个网卡地址，同时端口改为随机的或指定的值

上面这些目标都会改变IP封包的首部。

用于过滤封包，使用ACCEPT、DROP之类的目标

表中存放的是一个个规则，规则由匹配+目标组成。目标包括：

1. ACCEPT，允许封包通过，如果在子链ACCEPT，则相当于在父链也ACCEPT了，不会继续遍历父链后续规则
2. RETURN，从当前链返回，行为类似于编程语言函数中的return。如果当前：
   1. 位于子规则链，则返回到父链调用子链的那个规则的下一条规则处执行
   2. 不位于子规则链，则执行默认策略
3. DROP，直接丢弃数据包，不进行后续处理
4. REJECT，返回connection refused或者destination unreachable报文
5. QUEUE，将数据包放入用户空间的队列，供用户空间应用程序处理
6. JUMP，跳转到用户自定义链继续执行
7. LOG 让内核记录匹配的封包
8. AUDIT 对封包进行审计
9. DNAT 目标地址映射
10. SNAT 源地址映射
11. MASQUERADE 源地址映射，用于本机地址是动态获取的情况下

通常情况下，一旦匹配了某个规则，就会执行它的目标。同时，不再检查同规则链、同表的后续规则，这意味着规则的顺序非常重要。某些目标是例外，例如LOG、MARK，会继续遍历后面的规则

如果内置规则链执行到结尾，或者内置规则链中的某个目标是RETURN的规则匹配封包，那么规则链策略（Chain Policy）中定义的目标将决定如何处理当前封包。

连接跟踪（Connection tracking ）的目的是，让Netfilter框架能够知晓每个连接的状态。你可以使用

--state

注意，为了更加准确的跟踪TCP连接，内核还维护一系列的内部状态。这些内部状态不能用来匹配。

在iptables中，每个封包都可能和一个被跟踪的连接相关联。连接可以处于4种不同的状态：

在内核中，连接跟踪由conntrack模块负责。

除了本地生成的包，在OUTPUT中跟踪之外，所有连接跟踪都在PREROUTING链中进行。例如：

1. 本地发起一个连接的初始封包，则在OUTPUT链中，连接变为NEW
2. 当接收到上述封包的应答包后，在PREROUTING链中，连接变为ESTABLISHED

如果外部发起初始封包，则NEW状态是在PREROUTING中产生的。

iptables [-t table] {-A|-C|-D} chain rule-specification
ip6tables [-t table] {-A|-C|-D} chain rule-specification
iptables [-t table] -I chain [rulenum] rule-specification
iptables [-t table] -R chain rulenum rule-specification
iptables [-t table] -D chain rulenum
iptables [-t table] -S [chain [rulenum]]
iptables [-t table] {-F|-L|-Z} [chain [rulenum]] [options...]
iptables [-t table] -N chain
iptables [-t table] -X [chain]
iptables [-t table] -P chain target
iptables [-t table] -E old-chain-name new-chain-name

其中：
rule-specification = [matches...] [target]
match = -m matchname [per-match-options]
target = -j targetname [per-target-options]

带-n参数时，0.0.0.0/0表示匹配任何地址（anywhere）
不带-n参数时，所有保留私有地址都会显示为bogon

选项被分为若干组：

-t --table table 指定命令操控的表格的名称，如果内核被配置为自动模块加载方式，并且相应模块不存在，将尝试自动加载适当的模块

该组选项指定期望执行的动作，仅其中一个可以在命令行中指定
-A　--append chain rule-specification 附加一个或者多个规则到目标规则链。如果源/目标名称解析到多于一个地址，那么规则将会添加到每个可能的地址组合
-C　--check chain rule-specification 检查目标规则链是否具有匹配的规则，该命令与-D的逻辑类似，但是不会修改当前的iptables配置，使用其退出码来指示是否成功
-D　--delete chain rule-specification 从目标规则链中删除一个或者多个规则，需要指定规则的匹配规则
-D　--delete chain rulenum 从目标规则链中删除一个或者多个规则，需要指定从1开始的个数
-I　--insert chain [rulenum] rule-specification 插入一个或者多个规则到目标规则链的指定位置，如果rulenum是1则插到最前面，举例：

-I FORWARD 1

iptables --policy INPUT DROP  # 设置INPUT的规则链策略为DROP

-E　--rename-chain old-chain new-chain 重命名用户定义的规则链

以下的参数用来组成一个rule specification
[!]　-p, --protocol protocol 用来检查的规则或者封包的协议。支持的值包括：tcp, udp, udplite, icmp, icmpv6,esp, ah, sctp, all。叹号用来反转测试，默认all
[!]　-s, --source address[/mask][,...] 封包来源规则，address可以是网络名、主机名、IP地址（附加/掩码）、或者普通IP地址。主机名仅仅会在规则提交到内核前解析一次。叹号用来反转地址规则。指定多个地址是可以的，但是会被分解为多个规则，或者导致多个规则被删除（-D）
[!]　-d, --destination address[/mask][,...] 封包目标规则，类似来源规则
-m　--match match 指定使用的match，所谓match是用来测试特定属性的扩展模块
-j　--jump target 指定规则的目标，即：当规则匹配的时候要做什么。目标可以是用户定义的规则链、一个特殊的内置目标（立即决定封包命运）、或者一个扩展。如果某个规则不设置该选项，那么匹配后将对封包不构成任何影响，但是规则的计数器会增加
-g　--goto chain 仅仅用在用户定义的规则链中，指示重定向到另外一个链继续处理。和-j不同，-j后子链完成匹配后会跳转到父链，-g则不会跳转，如果子链没有匹配的规则则按子链的默认策略处理
[!]　-i, --in-interface name 仅用于进入INPUT, FORWARD, PREROUTING链的封包。限制接收到封包的网络接口名称，如果名称后面跟着+号，所有以该名称开头的接口都被匹配
[!]　-o, --out-interface name 仅用于进入FORWARD, OUTPUT, POSTROUTING链的封包。限制封包将被送出的网络接口名称，如果名称后面跟着+号，所有以该名称开头的接口都被匹配
[!]　-f, --fragment 对于分片的IP数据报，该规则将仅仅用于第二个或者以后的的分片。仅用于IPv4 　
-c　--set-counters packets bytes 在INSERT, APPEND, REPLACE规则时，用于初始化封包、字节计数器

-v　--verbose 冗长输出，list命令将输出接口名称、规则选项、TOS掩码、包以及字节计数器。对于附加、插入、删除、替换规则的操作，该选项导致规则的详细信息被打印
-w　--wait 等待xtables锁被解开，为了防止多个进程同时修改，iptables具有锁定机制
-n　--numeric 数字化输出，IP地址和端口将使用数字格式
-x　--exact 仅与-L命令有关，显示精确的封包、字节计数，使用1024而不是1000作为倍率
--line-numbers 列出规则时，显示行号
--modprobe=command 当添加、删除规则时，使用命令command加载必要的模块（目标、匹配-m扩展等）

# 发送任何目的端口为25的封包给在127.0.0.1:10025上监听的进程
# 并且给封包以标记 1 
iptables -t mangle -A PREROUTING -p tcp --dport 25 -j TPROXY \
  --tproxy-mark 0x1/0x1 --on-port 10025 --on-ip 127.0.0.1


# PREROUTING链之后，转发之前，检查路由表
# 如果发现封包被标记为 1，那么查找100号表
ip rule add fwmark 1 lookup 100

# 100号路由表，将封包通过lo发出。注意出口为lo的封包不会真正路由，而是交给本地进程处理
ip route add local 0.0.0.0/0 dev lo table 100

# 对于准备从wlan0出去的封包，进行源地址映射
iptables -t nat -A POSTROUTING -o wlan0 -j MASQUERADE

# 允许转发来自eth0、发往wlan0的封包
iptables -A FORWARD -i eth0 -o wlan0 -j ACCEPT

# 对于来自wlan0、发往wlan0的封包，如果状态为RELATED,ESTABLISHED则允许通过
# ESTABLISHED，封包属于一个已经建立的连接
# RELATED，封包创建了新连接，但是此连接和一个已经存在的连接相关，例如FTP数据传输器、ICMP错误
iptables -A FORWARD -i wlan0 -o eth0 -m state --state RELATED,ESTABLISHED -j ACCEPT

# 列出filter表（可用于实现防火墙）内容。注意默认网卡信息不显示，需要加 -v
iptables -t filter -L -n

# 禁止向目标地址发送网络包
iptables -A OUTPUT -j DROP -d 10.5.39.223
# 撤销
iptables -D OUTPUT -j DROP -d 10.5.39.223

# 禁止PING
iptables -I INPUT -p icmp --icmp-type 8 -j DROP
# 撤销
iptables -D INPUT -p icmp --icmp-type 8 -j DROP

# 禁止向目标网络转发包
iptables -A FORWARD -d 172.27.0.0/16 -j DROP
iptables -D FORWARD -d 172.27.0.0/16 -j DROP

# 取消Docker的网络隔离
iptables -I DOCKER-USER 1 -j ACCEPT
# 或者                                 两个Docker网络的网段
iptables -t filter -I DOCKER-USER   -s 172.17.0.0/16 -j ACCEPT
iptables -t filter -I DOCKER-USER   -s 172.21.0.0/16 -j ACCEPT

# 显示Filter表的详细信息，格式化输出
sudo iptables -L -nv -t filter | column -t -s " "

# 作为VPN服务器的主机，启用ipv4转发
iptables -t nat -L -v -n
# 输出如下：
# ...
# Chain POSTROUTING (policy ACCEPT 0 packets, 0 bytes)
#  pkts bytes target     prot opt in     out     source               destination
# 66404 4468K MASQUERADE  all  --  any    any     anywhere             anywhere

# 删除既有的IP掩蔽设置，针对所有封包做了端口映射
iptables -t nat -D POSTROUTING -j MASQUERADE
# 这时再连接到gmem.cc的VPN，发现无法上外网了
# 原因是，没有合适的端口映射，gmem.cc无法将封包发回给VPN客户端

# 修改后的IP掩蔽配置，限制了源IP地址的范围、出口网卡
iptables -t nat -A POSTROUTING -m iprange --src-range 172.21.0.100-172.21.0.120 -o eth0 -j MASQUERADE

# 把针对本机192.168.0.89的7777端口的请求全部转换为对虚拟机172.16.87.132的80端口的请求
sudo iptables -t nat -A PREROUTING         # 入站后第一个链
              -p tcp --dport 7777 -i eth0  # 如果封包来自eth0且目标端口为7777
              -j DNAT --to-destination 172.16.87.132:80 # 那么修改目标地址为虚拟机的80端口

# 此时，针对192.168.0.89:7777的封包，目的地址已经改为172.16.87.132
# 允许对目的地址为172.16.87.132的封包进行转发，可能发生的情况是：
# 原始数据报 
# 192.168.0.200:23387 => 192.168.0.89:7777
# 入站后，目标地址被映射：
# 192.168.0.200：23387 => 172.16.87.132：80
# 转发：由于目的地址不是本机，因此进行转发，ipv4转发功能已经开启过
# 出站前，源地址被映射被映射：
# 172.16.87.1:39480 => 172.16.87.132：80 
# 这就为本机39480端口和192.168.0.200：23387建立了映射关系
sudo iptables -t nat -A POSTROUTING -p tcp -d 172.16.87.132 --dport 80 -j MASQUERADE
# 上面的命令也可以替换为：
sudo iptables -t nat -A POSTROUTING -p tcp -d 172.16.87.132 --dport 80 -j SNAT --to-source 172.16.87.1
# 返回的数据报，处理时，自动逆向映射：原先的目标映射用于逆向源映射，原先的源映射用于逆向目标映射
# 原始数据报
# 172.16.87.132：80 => 172.16.87.1:39480
# 入站后，目标地址被映射
# 172.16.87.132：80 => 192.168.0.200：23387
# 出站前，源地址被映射
# 192.168.0.89:7777 => 192.168.0.200：23387

# ✭✭✭ 一个重要的原则是，仅仅去匹配初始发起连接的包，做好NAT后，返回的包自动映射

很多iptables命令都要求提供一个规则的规格（rule-specification，后面简称规则）。规则实际上就是一系列iptables命令选项，大部分选项都用来说明如何匹配封包的，

-j

要为规则添加注释，参考：

iptables -m comment --comment "comment here"
iptables -A INPUT -i eth1 -m comment --comment "my LAN - " -j DROP

可以看到，注释以匹配扩展的形式被支持。

注释最多256字符，执行

iptables -L

/* */

这些匹配选项的值，前面都可以加

!

! -f

--source-port 22:80

举例：

# 匹配SYN标记被设置，ACK,FIN,RST没有被设置的封包
iptables -A FORWARD -p tcp --tcp-flags SYN,ACK,FIN,RST SYN

所谓显式匹配，是指必须明确通过

-m

--match

内核中基于netfilter框架实现的连接跟踪模块即conntrack。在DNAT时，conntrack使用状态机来跟踪连接的状态，记住目的地址被从什么改成了什么，这样才能将回程包的源地址改回来

基于连接跟踪的匹配。使用

-m conntrack

-m conntrack --ctstate ESTABLISHED,RELATED

-m conntrack ! --ctstate ESTABLISHED,RELATED

-m conntrack ! --ctproto TCP

-m conntrack --ctorigsrc 192.168.0.0/24

使用IP地址范围进行匹配。使用

-m iprange

-m iprange --src-range 192.168.1.13-192.168.2.19

-m iprange --dst-range 192.168.1.13-192.168.2.19

第三层载荷匹配。该扩展用于根据网络层载荷，即传输层封包的长度进行匹配

用法：

-m length [!] --length length[:length] TCP/UDP包的长度

可以用于限制特定规则的日志记录的频度。使用

-m limit

-m limit --limit 3/hour

根据源地址的MAC地址进行匹配，只能用在PREROUTING, FORWARD,INPUT 规则链。

示例：

-m mac --mac-source 00:00:00:00:00:01

根据关联当前封包的netfilter标记进行匹配。mark是一个特殊字段，无符号整数（unsigned int），仅仅在内核中维护（不会嵌入在封包里）。封包在通过主机时，标记可以和它关联。

很多内核例程都会使用mark，从而完成流量塑形（Traffic Shaping）、过滤等工作。

要设置一个mark，可以使用iptables的MARK目标。由于以前在ipchains的FWMARK目标中设置，现在仍然会使用FWMARK这个术语。

示例：

-m mark --mark 1986

-m mark --mark 1/1

多端口匹配。该扩展只能用于以下协议：tcp, udp, udplite, dccp, sctp。最多指定15个端口

指定端口的语法：

port[,port|,port:port]

使用

-m multiport

-m multiport --source-port 22,53,80,110

根据创建封包的进程的身份来匹配封包，很明显，只能用于本机产生的封包上，你只能在OUTPUT链中使用该匹配。

使用

-m owner

根据链路层类型匹配。用法 

-m pkttype [!] --pkt-type {unicast|broadcast|multicast}

和内核中的连接跟踪代码配合工作。此匹配会从连接跟踪状态机中读取封包的状态。

示例：

-m state --state RELATED,ESTABLISHED

根据TCP的Maximum Segment Size来匹配，仅仅针对SYN或SYN/ACK包。

示例：

iptables -A INPUT -p tcp --tcp-flags SYN,ACK,RST SYN -m tcpmss --mss 2000:2500

根据Type Of Service来匹配。示例：

iptables -A INPUT -p tcp -m tos --tos 0x16

根据Time To Live来匹配。示例：

iptables -A OUTPUT -m ttl --ttl 60

通过封包的地址类型进行匹配，可用的地址类型包括：

使用

-m addrtype

根据某个连接到目前为止发送的字节数、封包数，或者每封包平均字节数进行匹配，计数器64位长。

该扩展可以用来检测维持了很长时间的下载，并将其安排到低优先级，以进行带宽控制。

使用

-m connbytes

可用于限制一个客户端可以连接到某个服务的并发连接数。可以接额外选项：

示例：

# 允许每个客户端主机开启两个telnet连接
iptables -A INPUT -p tcp --syn --dport 23  -m connlimit --connlimit-above 2 -j REJECT
# 限制每个C类地址网段（例如192.168.0.*）最多总计建立16个HTTP连接 
iptables -p tcp --syn --dport 80 -m connlimit   --connlimit-above 16 --connlimit-mask 24 -j REJECT

基于关联到连接的netfilter mark字段进行匹配，此mark由CONNMARK目标来设置。

用法：

-m connmark [!] --mark value[/mask]

示例：

#                            匹配所属连接被标记为123的封包
#                                                   将连接的标记拷贝到封包上
iptables -t mangle -I OUTPUT -m connmark --mark 123 -j CONNMARK --restore-mark

类似于connmark，但是标签是按位的（每个标签占一个bit），全系统支持最多128个标签

匹配条件：

1. 针对包进行套接字查找（Socket lookup），如果发现存在打开的TCP/UDP套接字，也就是说SRC_IP:SRC_PORT:DST_IP:DST_PORT作为已建立的（established）套接字存在于本地TCP/IP栈，则匹配
2. 存在established的监听套接字，则匹配
3. 存在非零绑定的监听套接字（non-zero bound listening socket），甚至在非本地地址上监听，则匹配。所谓zero bound应该就是指绑定到0.0.0.0

简而言之，就是匹配应当由本地TCP/IP栈处理（而非转发）的封包。进行套接字查找时，使用packet元组，或者嵌入在 ICMP/ICPMv6错误报文中的原始TCP/UDP头

可以接额外选项：

这个匹配扩展+MARK+策略路由，就能够实现全功能的non-locally bound套接字。常常用于配合优化透明代理。通常是匹配后进行MARK，然后具有此MARK的封包路由设置到lo。

从各种文档中看到关于socket match的说明，都不是非常明朗，导致理解起TPROXY拦截模式下Istio的iptables规则有些困难：

# mangle表

target     prot opt source               destination         
ISTIO_INBOUND  tcp  --  0.0.0.0/0            0.0.0.0/0           

Chain INPUT (policy ACCEPT)
target     prot opt source               destination         

Chain FORWARD (policy ACCEPT)
target     prot opt source               destination         

Chain OUTPUT (policy ACCEPT)
target     prot opt source               destination         

Chain POSTROUTING (policy ACCEPT)
target     prot opt source               destination         

Chain ISTIO_DIVERT (1 references)
target     prot opt source               destination         
MARK       all  --  0.0.0.0/0            0.0.0.0/0            MARK set 0x539
LOG        tcp  --  0.0.0.0/0            0.0.0.0/0            tcp dpt:80 LOG flags 0 level 4 prefix "dst-80-socket-matched: "
ACCEPT     all  --  0.0.0.0/0            0.0.0.0/0           

Chain ISTIO_INBOUND (1 references)
target     prot opt source               destination         
RETURN     tcp  --  0.0.0.0/0            0.0.0.0/0            tcp dpt:22
RETURN     tcp  --  0.0.0.0/0            0.0.0.0/0            tcp dpt:15090
RETURN     tcp  --  0.0.0.0/0            0.0.0.0/0            tcp dpt:15020
ISTIO_DIVERT  tcp  --  0.0.0.0/0            0.0.0.0/0            socket
ISTIO_TPROXY  tcp  --  0.0.0.0/0            0.0.0.0/0           

Chain ISTIO_TPROXY (1 references)
target     prot opt source               destination         
LOG        tcp  --  0.0.0.0/0            0.0.0.0/0            tcp dpt:80 LOG flags 0 level 4 prefix "dst-80-before-tproxy: "
TPROXY     tcp  --  0.0.0.0/0           !127.0.0.1            TPROXY redirect 0.0.0.0:15001 mark 0x539/0xffffffff

这是一个启用了TPROXY拦截模式的Pod的iptables，LOG目标是我添加用于分析socket match的行为的。此Pod的地址是172.27.121.156。可以看到它在监听：

# netstat -nlt
# Active Internet connections (only servers)
# Proto Recv-Q Send-Q Local Address           Foreign Address         State      
tcp        0      0 0.0.0.0:80              0.0.0.0:*               LISTEN   

现在我们从另一个客户端

172.27.155.65

curl http://172.27.121.156

这会发起一个TCP连接，它的SYN包，是否匹配socket扩展呢？我们回顾一下它的匹配条件：

1. 套接字查找成功，这个不满足。因为是新连接
2. 已经建立的监听套接字，这个不满足，监听套接字还没有收到SYN，谈不上建立
3. 存在non-zero bound listening socket。这个说的让人费解。但是肯定隐含着在SYN包的目的地址上监听。此SYN包的目的地址是172.27.121.156:80，我们知道Pod在0.0.0.0:80上监听了，那么172.27.121.156作为它的本地地址，自然也在其上监听。那么，这个监听套接字，是不是non-zero bound的呢？网上很难找到相关信息，我的理解，zero bound就是指绑定到0.0.0.0。在这种猜测之下，是不匹配socket的

根据iptables日志来验证一下。客户端curl之后，在Pod的内核看到一下日志：

# 客户端发来的SYN，可以看到不匹配socket，直接走到TPROXY，这证明了上述猜测
dst-80-before-tproxy: IN=eth0 OUT= SRC=172.27.155.65 DST=172.27.121.156 LEN=60 SYN URGP=0 
# 客户端发来的ACK，注意反方向报文没有日志
# 这此匹配socket了，因为满足了1，套接字查找成功
dst-80-socket-matched: IN=eth0 OUT= SRC=172.27.155.65 DST=172.27.121.156 LEN=52 ACK URGP=0 MARK=0x539 
# 这次应该是客户端发送HTTP请求报文了
dst-80-socket-matched: IN=eth0 OUT= SRC=172.27.155.65 DST=172.27.121.156 LEN=130 ACK PSH URGP=0 MARK=0x539 
# 这里是Envoy发给80端口进程，首个报文，但是不会TPROXY，因为目的地址不满足要求
dst-80-before-tproxy: IN=lo OUT= SRC=127.0.0.1 DST=127.0.0.1 LEN=60 TOS=0x00 PREC=0x00 SYN URGP=0 
# 套接字查找成功，都不再走TPROXY了
dst-80-socket-matched: IN=lo OUT= SRC=127.0.0.1 DST=127.0.0.1 LEN=52 TOS=0x00 PREC=0x00 ACK URGP=0 MARK=0x539 
dst-80-socket-matched: IN=lo OUT= SRC=127.0.0.1 DST=127.0.0.1 LEN=322 TOS=0x00 PREC=0x00 ACK PSH URGP=0 MARK=0x539 
dst-80-socket-matched: IN=lo OUT= SRC=127.0.0.1 DST=127.0.0.1 LEN=52 TOS=0x00 PREC=0x00 ACK URGP=0 MARK=0x539 
dst-80-socket-matched: IN=lo OUT= SRC=127.0.0.1 DST=127.0.0.1 LEN=52 TOS=0x00 PREC=0x00 ACK URGP=0 MARK=0x539 
# 80进程处理完，报文返回Envoy，Envoy又返回给客户端。客户端发起后续报文，包括FIN
dst-80-socket-matched: IN=eth0 OUT= SRC=172.27.155.65 DST=172.27.121.156 LEN=52 TOS=0x00 ACK URGP=0 MARK=0x539 
dst-80-socket-matched: IN=eth0 OUT= SRC=172.27.155.65 DST=172.27.121.156 LEN=52 TOS=0x00 ACK URGP=0 MARK=0x539 
dst-80-socket-matched: IN=eth0 OUT= SRC=172.27.155.65 DST=172.27.121.156 LEN=52 TOS=0x00 ACK FIN URGP=0 MARK=0x539 
dst-80-socket-matched: IN=eth0 OUT=  SRC=172.27.155.65 DST=172.27.121.156 LEN=52 TOS=0x00 ACK URGP=0 MARK=0x539 
dst-80-socket-matched: IN=lo OUT= SRC=127.0.0.1 DST=127.0.0.1 LEN=52 TOS=0x00 PREC=0x00 ACK FIN URGP=0 MARK=0x539

IPSet扩展，可以匹配一组IP。使用

-m set

[!] --match-set setname flag[,flag]...

iptables -A FORWARD -m set --match-set test src,dst

使用Linux Socket Filter来过滤，需要提供十进制形式的（由nfbpf_compile生成）BPF字节码。

示例：

iptables -A OUTPUT -m bpf --bytecode '4,48 0 0 9,21 0 1 6,6 0 0 1,6 0 0 0' -j ACCEPT
# 等价写法
iptables -A OUTPUT -m bpf --bytecode "`nfbpf_compile RAW 'ip proto 6'`" -j ACCEPT

根据处理封包的CPU来匹配。示例：

# 如果是第一个核心处理了封包，则重定位到8080端口
iptables -t nat -A PREROUTING -p tcp --dport 80 -m cpu --cpu 0 -j REDIRECT --to-port 8080
# 如果是第二个核心处理了封包，则重定位到8081端口
iptables -t nat -A PREROUTING -p tcp --dport 80 -m cpu --cpu 1 -j REDIRECT --to-port 8081

根据封包到达时间来匹配。 

使用选项

-j

1. 自定义链的名称，这导致跳转到自定义的链继续执行

接收封包，不再遍历当前链的其它规则、也不会在遍历当前表中的任何规则。但是，在一个链中被接收的封包，可能仍然需要经过其它表中的链，仍然可能被DROP。

在子链中ACCEPT的效果，等价于在父链中被ACCEPT。

停止遍历当前链：

1. 如果当前位于子链，则回到父链，继续执行后面的规则
2. 如果当前位于主链，则执行默认策略

静默的丢弃封包，不会在对它进行任何后续处理。

可能会导致对方主机上出现一个僵尸套接字，最好用REJECT代替。

用于发送一个错误报文给匹配封包的发送者，其它方面，该目标的行为与DROP一致：丢弃封包，终止规则遍历。

该目标仅用于INPUT, FORWARD, OUTPUT规则链中，或者从这两规则链调用的用户自定义规则链。

额外选项：

允许创建命中目标的封包的审计记录，用来记录被接受的、丢弃的、拒绝的封包。

用法：

-j AUDIT --type {accept|drop|reject}

示例：

# 添加一个规则链到默认表格
iptables -N AUDIT_DROP
# 审计丢弃包的动作
iptables -A AUDIT_DROP -j AUDIT --type drop
# 丢弃包
iptables -A AUDIT_DROP -j DROP

这是一个非终止性目标，后续规则总是会被执行。如果你希望LOG后DROP，在此规则后面紧跟着一个相同匹配的目标为DROP的规则。

让内核记录匹配的封包。内核将会打印匹配的封包的信息，包括大部分IP头字段。这些日志可以在dmesg/syslog中看到。

额外选项：

关于容器中的iptables logging：

1. 默认情况下，来自容器（非全局网络命名空间）的iptable logging被忽略，你无法在

   dmesg -w

   中看到
2. 要改变此行为，你需要较新版本的内核，并且设置：

   echo 1 > /proc/sys/net/netfilter/nf_log_all_netns

仅用于nat表的PREROUTING,OUTPUT规则链，或者从这两规则链调用的用户自定义规则链。

该目标指定封包的目的地址应当被修改（且该连接上所有以后的封包应当执行同样的操作），规则应当停止检查。

应用场景：HTTP服务放置在内网主机上，前端有个防火墙配置公网IP，互联网用户通过此公网IP访问内网主机上的HTTP服务，这种情况需要DNAT

额外选项： 

举例：

# 如果公网客户端访问本防火墙的80端口
# 那么将其目标地址改写为192.168.0.200，目标端口不变
iptables -t nat 
         -A PREROUTING 
         -d 106.185.46.7
         --dport 80
         -j DNAT --to-destination 192.168.0.200

仅用于nat表的POSTROUTING,INPUT规则链，或者从这两规则链调用的用户自定义规则链。

该目标指定封包的源地址应当被修改（且该连接上所有以后的封包应当执行同样的操作），规则应当停止检查。

应用场景：局域网前端有个防火墙配置公网IP，内网主机通过该IP访问公网，为了内网主机能够访问外网，需要SNAT。

额外选项：

举例：

# 对于来自192.168.0.0网段的所有出站请求
# 如果这些封包将通过eth0接口（外网网卡）传出去
# 那么，将封包源地址改写为106.185.46.7（即eth0的IP地址）
iptables -t nat -A POSTROUTING 
         -s 192.168.0.0/255.255.255.0 
         -o eth0 
         -j SNAT --to-source 106.185.46.7

仅用于nat表的POSTROUTING规则链。应当用于动态分配IP的网络连接，静态网络连接应当使用SNAT目标。该目标会自动从网络接口上获取当前IP地址，用来做源地址的SNAT

应用场景：本主机具有动态分配的公网地址，有客户端通过PPP连接（VPN）到本主机，并通过本主机上网。这时需要将客户端封包的源地址（PPP对端地址）转换为公网地址，但是由于本主机的公网地址是动态获取的，因此不能使用SNAT，只能使用MASQUERADE

额外选项：

举例：

iptables -t nat -A POSTROUTING 
         -s 192.168.0.0/255.255.255.0 
         -o eth0 
         -j MASQUERADE

仅可用在mangle的PREROUTING链（或者从该链调用的用户自定义链）。此目标能够重定向包到一个本地套接字，但却不修改包头的任何信息。 它还能够改变封包的mark，进而辅助后续的策略路由。

额外选项：

可以认为是一种DNAT。

仅用于nat表的PREROUTING,OUTPUT规则链，或者从这两规则链调用的用户自定义规则链。该目标重定向封包到当前主机本身，通过把目的地址改写为入站网卡的主地址（本地生成的封包映射到localhost地址，对于IPv4即127.0.0.1）。

额外选项：

在连接上设置netfilter标记。标记为32bit。

额外选项：

在封包上设置netfilter标记。标记为32bit。

常常和基于fwmark的路由（需要iproute2）联用，这种情况下你需要在PREROUTING链mangle表中使用，以影响路由策略。

额外选项：

只能用于mangle表，可以为封包添加缺失的校验和

可以用于识别某个网络接口已经空闲一定的时间

允许静态的把整个网络的IP地址映射到另外一个网络的IP地址

用于记录匹配包的日志

禁止匹配规则的封包的连接跟踪。你无法通过conntrack命令看到这样的连接

修改TCP的SYN封包的MSS值，用来控制连接的最大单个段的大小，一般限制到出站网络接口MTU-40

该目标用于修改封包的TTL

假设内网客户端机器IP地址为10.0.0.1；NAT网关内网地址10.0.0.2，外网地址10.4.80.14；外网服务器地址为9.135.102.75。

我们可以通过conntrack命令，在NAT网关上查看相关事件：

conntrack -E --proto tcp -d 9.135.102.75

    [NEW] tcp      6 120 SYN_SENT src=10.0.0.1 dst=9.135.102.75 sport=56736 dport=36000 
                   [UNREPLIED] src=9.135.102.75 dst=10.4.80.14 sport=36000 dport=56736
 [UPDATE] tcp      6 60 SYN_RECV src=10.0.0.1 dst=9.135.102.75 sport=56736 dport=36000 
                               src=9.135.102.75 dst=10.4.80.14 sport=36000 dport=56736
 [UPDATE] tcp      6 432000 ESTABLISHED src=10.0.0.1 dst=9.135.102.75 sport=56736 dport=36000 
                               src=9.135.102.75 dst=10.4.80.14 sport=36000 dport=56736 [ASSURED]
 [UPDATE] tcp      6 120 FIN_WAIT src=10.0.0.1 dst=9.135.102.75 sport=56736 dport=36000 
                               src=9.135.102.75 dst=10.4.80.14 sport=36000 dport=56736 [ASSURED]
 [UPDATE] tcp      6 60 CLOSE_WAIT src=10.0.0.1 dst=9.135.102.75 sport=56736 dport=36000 
                               src=9.135.102.75 dst=10.4.80.14 sport=36000 dport=56736 [ASSURED]
 [UPDATE] tcp      6 30 LAST_ACK src=10.0.0.1 dst=9.135.102.75 sport=56736 dport=36000 
                               src=9.135.102.75 dst=10.4.80.14 sport=36000 dport=56736 [ASSURED]
 [UPDATE] tcp      6 120 TIME_WAIT src=10.0.0.1 dst=9.135.102.75 sport=56736 dport=36000 
                               src=9.135.102.75 dst=10.4.80.14 sport=36000 dport=56736 [ASSURED]
 # 过了2MSL
 [DESTROY] tcp      6 src=10.0.0.1 dst=9.135.102.75 sport=56736 dport=36000 
                               src=9.135.102.75 dst=10.4.80.14 sport=36000 dport=56736 [ASSURED]

NAT表的特殊之处在于，仅新连接的第一个封包会经过此表。第一个封包的地址转换结果，会应用到连接的所有后续封包。

NAT网关接收到新连接后，创建conntrack条目：

10.0.0.1:56736->9.135.102.75:36000, 9.135.102.75:36000-> 10.0.0.1:56736

在iptables中，NAT网关的POSTROUTING钩子中的SNAT规则，会修改conntrack的应答目的地址

10.0.0.1:56736->9.135.102.75:36000, 9.135.102.75:36000->10.4.80.14:56736

这时，就到达上面命令输出的[NEW]状态了。请求/应答报文进行地址转换所需的信息已经完备。

iptables规则所做的事情，仅仅是修改conntrack规则而已。所有其它事情，包括请求封包的源地址修改，是由内核中的conntrack模块（nf_conntrack、nf_conntrack_ipv4）以及nat模块（nf_nat、nf_nat_ipv4）等负责的。

当NAT网关接收到应答报文后，会检索conntrack中的条目，并将匹配的条目关联到该封包（

skb->_nfct

注意以下几点：

1. iptables不是netfilter本身，它是netfilter的用户。而conntrack和nat模块是netfilter的一部分
2. 无法在POSTROUTING钩子+NAT表看到检查到应答报文，因为NAT表仅仅对新连接调用一次
3. 连接跟踪、NAT转换的大部分工作由相应内核模块，而不是iptables完成

在iptables新老版本中，xtables锁的实现不同。在1.4.x中，锁基于abstract unix domain socket实现；1.6.x中则基于普通文件。

func grabIptablesLocks(lockfilePath string) (iptablesLocker, error) {
	var err error
	var success bool

	l := &locker{}
	defer func(l *locker) {
		// Clean up immediately on failure
		if !success {
			l.Close()
		}
	}(l)

	// iptables 1.6.x和1.4.x版本的锁是不一样的
	// 1.6.x的锁文件是：/run/xtables.lock
	// 下面的逻辑是1.6.x xtables_lock() 函数的粗略的重复实现
	l.lock16, err = os.OpenFile(lockfilePath, os.O_CREATE, 0600)
	if err != nil {
		return nil, fmt.Errorf("failed to open iptables lock %s: %v", lockfilePath, err)
	}


	// 尝试加锁（1.6.x版本）
	if err := wait.PollImmediate(200*time.Millisecond, 2*time.Second, func() (bool, error) {
		if err := grabIptablesFileLock(l.lock16); err != nil {
			return false, nil
		}
		return true, nil
	}); err != nil {
		return nil, fmt.Errorf("failed to acquire new iptables lock: %v", err)
	}

	// 下面的逻辑是1.4.x xtables_lock() 函数的粗略的重复实现
	if err := wait.PollImmediate(200*time.Millisecond, 2*time.Second, func() (bool, error) {
		// 1.4.x的锁是抽象Unidx Domain socket
		// 前缀的@表示套接字位于抽象命名空间（abstract namespace），不体现为文件系统中的文件
		l.lock14, err = net.ListenUnix("unix", &net.UnixAddr{Name: "@xtables", Net: "unix"})
		if err != nil {
			return false, nil
		}
		return true, nil
	}); err != nil {
		return nil, fmt.Errorf("failed to acquire old iptables lock: %v", err)
	}

	success = true
	return l, nil
}

// 加1.6锁
func grabIptablesFileLock(f *os.File) error {
	//                             独占         非阻塞
	return unix.Flock(int(f.Fd()), unix.LOCK_EX|unix.LOCK_NB)
}

尝试修改iptables时，可能会因为锁被占用导致报错。这种报错没有专门的退出码，因此只能比对stderr输出来判定。

正常情况下，出现锁争用的概率比较低，可以使用下面的命令显式占用xtables锁：

# 1.4.x加锁
socat ABSTRACT-LISTEN:xtables -

# 1.6.x加锁
flock -x /run/xtables.lock sleep 365d

保持运行上述两个命令的Terminal打开，然后插入iptables规则。可以看到报错信息如下：

1. v1.4.21版本：
   1. 不带-w参数：Another app is currently holding the xtables lock. Perhaps you want to use the -w option?
   2. 带有-w参数：Another app is currently holding the xtables lock; still 21s 0us time ahead to have a chance to grab the lock... Another app is currently holding the xtables lock. Stopped waiting after 30s.
2. v1.6.0版本：报错同上

实际上，K8S中就是基于上述输出信息进行判断的：

func IsProxyLocked(err error) bool {
	return strings.Contains(err.Error(), "holding the xtables lock")
}

The post 重温iptables appeared first on 绿色记忆.

BCC是一个工具包，用来创建高效的、在内核中运行的性能追踪程序。它首先是一个编译器，能够将你写的代码编译为eBPF程序，此外，它还提供了大量有用的工具和样例

BCC的基础是eBPF，因此其大部分功能需要内核版本在4.1+才能使用，其提供的某些根据甚至需要4.4或4.6版本的内核。要编译和运行BCC程序，你除了需要安装bcc之外，还需要llvm/clang，以及内核头文件。

BCC的支持内核中多种追踪机制，包括kprobe、uprobe、tracepoint、USDT（User-level statically defined tracing probes ），能够监控块设备IO、TCP函数、文件系统操作、任何syscall、Node.js/Java/MySQL/libc等多种常用软件/平台定义的USDT。

在网络监控方面，BCC提供了分布式网桥、HTTP过滤器、快速封包丢弃、隧道监控等样例代码。

BCC通过以下途径让eBPF开发变得简单：

1. 在C中使用kernel instrumentation，提供了LLVM的一个C wrapper
2. 提供Python和Lua的前端

要使用BCC，你通常需要4.1或者更新版本的内核，并且启用以下内核配置：

CONFIG_BPF=y
CONFIG_BPF_SYSCALL=y
# [optional, for tc filters]
CONFIG_NET_CLS_BPF=m
# [optional, for tc actions]
CONFIG_NET_ACT_BPF=m
CONFIG_BPF_JIT=y
# [for Linux kernel versions 4.1 through 4.6]
CONFIG_HAVE_BPF_JIT=y
# [for Linux kernel versions 4.7 and later]
CONFIG_HAVE_EBPF_JIT=y
# [optional, for kprobes]
CONFIG_BPF_EVENTS=y
# Need kernel headers through /sys/kernel/kheaders.tar.xz
CONFIG_IKHEADERS=y

# Ubuntu
sudo apt-get install bpfcc-tools linux-headers-$(uname -r)
# CentOS
yum install bcc-tools

从0.10.0开始，BCC依赖libbpf，后者提供对BPF系统调用的包装函数，提供bpf.h / btf.h的UAPI头文件。

安装构建BCC需要的依赖，以及相关工具：

apt install -y bison build-essential cmake flex git libedit-dev \
    python3-distutils  llvm clang llvm-dev libclang-dev python zlib1g-dev libelf-dev libfl-dev

apt install arping netperf iperf3
ln -s `which python3` /usr/bin/python

编译并安装BCC：

git clone https://github.com/iovisor/bcc.git
mkdir bcc/build; cd bcc/build
cmake ..
make
sudo make install


cmake -DPYTHON_CMD=python3 .. # build python3 binding
pushd src/python/
make
sudo make install

BCC自带的工具位于

/usr/share/bcc/tools

我们可以先了解以下BCC提供的各种工具，这些工具可以直接用来解决性能追踪等问题，也是发明新轮子的重要参考。

下图显示了工作在系统各层次的工具列表：

在使用BCC之前，我们有必要回顾以下常用的Linux性能分析工具。

uptime 
23:51:26 up 21:31, 1 user, load average: 30.02, 26.43, 19.02

这个命令可以查看系统启动了多久，还可以快速查看工作负载情况。最后的三个数字分别是最近1/5/15分钟的、基于指数衰减移动和平均（exponentially damped moving sum averages）算法的工作负载信息。如果你发现第一个数字比第二个小很多，可能提示你错过了高负载时刻。

工作负载提示了有多少进程想要运行（去获得CPU）：包括积极等待被调度的进程，以及被不可中断睡眠（通常是块IO）阻塞的进程。

内核在重大事件发生后，都会输出信息到日志环：

dmesg | tail
# [1880957.563150] perl invoked oom-killer: gfp_mask=0x280da, order=0, oom_score_adj=0
# [1880957.563400] Out of memory: Kill process 18694 (perl) score 246 or sacrifice child
# [1880957.563408] Killed process 18694 (perl) total-vm:1972392kB, anon-rss:1953348kB, file-rss:0kB
# [2320864.954447] TCP: Possible SYN flooding on port 7001. Dropping request.  Check SNMP counters.

系统工作不正常是，有必要观察这些日志。

vmstat 1
# procs -----------memory---------- ---swap-- -----io---- -system-- ------cpu-----
#  r  b   swpd   free   buff  cache   si   so    bi    bo   in   cs us sy id wa st
#  1  0      0 35469380 1681776 43056984    0    0   673   552  174  706 17  8 74  1  0
#  4  0      0 35468148 1681776 43059452    0    0    12  3480 21357 44556  8  3 88  0  0
# 10  0      0 35467088 1681784 43059824    0    0    20  3212 23257 45228 14  5 81  0  0

这个工具给出系统的各种宏观统计信息：

1. r

   等待获得运行机会的CPU数量，比起load average，更明确的显示了CPU饱和度，因为它没有包含I/O，如果数量大于CPU核心，说明饱和了

2. free

   空闲内存KB

3. si

   /

   so

   换入/换出的页数量，如果非零提示内存不足

4. us

   ,

   sy

   ,

   id

   ,

   wa

   ,

   st

   处理器时间的分解：用户空间耗时，内核空间耗时，空闲时间，等待IO时间，被偷走的时间（虚拟化环境下被其它客户机偷走使用的）
   1. 如果us+sy高提示CPU繁忙、wa高则提示IO瓶颈
   2. 系统需要消耗sy时间来处理IO，如果sy时间总是很高，例如占比20%+，可能提示内核处理IO效率较差
   3. CPU利用90%+不一定说明CPU饱和，查看r列更靠谱

这个命令可以分别查看每个CPU核心的使用情况：

mpstat -P ALL 1                                                                                                                                                                          
# Linux 5.8.0-55-generic (zircon)         06/11/2021      _x86_64_        (16 CPU)
# 09:14:03 PM  CPU    %usr   %nice    %sys %iowait    %irq   %soft  %steal  %guest  %gnice   %idle
# 09:14:04 PM  all    2.95    0.00   10.39    0.80    0.00    0.00    0.00    0.68    0.00   85.18
# 09:14:04 PM    0    5.00    0.00    5.00    0.00    0.00    0.00    0.00    3.00    0.00   87.00
# 09:14:04 PM    1    6.06    0.00    5.05    0.00    0.00    0.00    0.00    0.00    0.00   88.89

能够用来发现CPU负载不均衡的情况。单个热点CPU，提示存在一个忙的单线程应用程序。

pidstat 1
# Linux 5.8.0-55-generic (zircon)         06/11/2021      _x86_64_        (16 CPU)

# 09:17:58 PM   UID       PID    %usr %system  %guest   %wait    %CPU   CPU  Command
# 09:17:59 PM  1000      2736    4.95    1.98    0.00    0.00    6.93     6  gnome-shell
# 09:17:59 PM  1000      6916    0.99    0.00    0.00    0.00    0.99    11  gnome-terminal-
# 09:17:59 PM  1000      7380    8.91   51.49    0.00    0.00   60.40     4  vmware-vmx

类似于top，但是滚动更新，有助于录制和事后分析或者发现特定的pattern。

iostat -x 1

用于了解块设备的工作情况：

1.  

   r/s

   ,

   w/s

   ,

   rkB/s

   ,

   wkB/s

   ：读写的次数、读写的字节数

2. await

   ：等待IO完成的平均ms

3. avgqu-sz

   ：平均发送给目标设备的请求数量，数量大于1提示饱和（尽管设备通常能够并行处理请求，特别是由多个后端磁盘组成的虚拟设备）

4. %util

   ：提示设备有多少时间百分比是忙着的。尽管取决于设备，大于60%通常会导致低性能。接近100%通常提示设备饱和。但是，对于多个后端磁盘组成的虚拟设备，100%仅仅提示所有时间都有后端磁盘在工作，但是可能远远没有饱和。

需要注意，很多应用程序都使用异步IO技术，这样即使设备饱和，应用程序也不会出现直接的（可被预读、缓冲写缓和）延迟。

free -m
#               total        used        free      shared  buff/cache   available
# Mem:         128677        6601       77687       12528       44389      108334
# Swap:         62499           0       62499

需要安装下面的软件：

apt install sysstat

修改配置文件：

ENABLED="true"

并重启服务：

systemctl restart sysstat.service

查看网络接口的吞吐情况：

sar -n DEV 1

# 接口     收包数    发包数      收KB      发KB                                   网卡利用率
  IFACE   rxpck/s   txpck/s    rxkB/s    txkB/s   rxcmp/s   txcmp/s  rxmcst/s   %ifutil
  lo      0.00      0.00      0.00      0.00      0.00      0.00      0.00      0.00

查看TCP统计信息：

sar -n TCP,ETCP 1

#            本地主动发起连接数量
#                     本地被动accept连接数量
#                                  
09:38:04 PM  active/s passive/s    iseg/s    oseg/s
09:38:05 PM      0.00      0.00      5.00      5.00

#                               重传次数
09:39:41 PM  atmptf/s  estres/s retrans/s isegerr/s   orsts/s
09:39:42 PM      0.00      0.00      0.00      0.00      0.00

这个工具可以探测新

exec()

fork()

该工具可用于发现短暂存在的、消耗CPU的进程，这些进程可能难以在周期性的、快照式的监控工具（例如top）中出现。

这个工具可以探测

open()

类似的工具还包括

btrfsslower

xfsslower

zfsslower

这些工具可以探测单个的、缓慢的文件系统操作。由于磁盘是异步处理IO的，难以将块设备层的延迟和应用程序的延迟关联起来。在VFS/文件系统接口层进行探测，更加接近应用程序，延迟相关的可能性也更大。

跟踪此片IO延迟（从向设备发起请求到处理完毕），退出此工具时会绘制直方图。

iostat之类工具能给出平均延迟，此工具则通过直方图显示延迟的分布情况。

按进程和延迟探测块IO操作。

按进程显示块IO的汇总信息。

每行打印统计周期内（默认1s）文件系统缓存命中、丢失、读/写操作缓存命中率。

追踪IPv4/IPv6的

bind()

该工具监控每一个新发起的主动TCP连接（通过

connect()

该工具监控每一个新发起的被动TCP连接（通过

accept()

每当出现一个TCP重传包时，该工具打印一行内容。

TCP重传会导致延迟和吞吐量问题。

对于ESTABLISHED状态连接的重传，需要检查网络patterns；对于SYN_SENT状态连接的重传，可能提示目标内核CPU饱和以及内核丢包。

显示线程在CPU运行队列上等待的时间的直方图。

在CPU饱和的情况下，该工具可以度量等待CPU消耗的时间。

以特定的周期，获取栈追踪采样，并且在结束时，打印每个独特的栈追踪的数量。

该工具可以辅助理解哪些代码路径消耗CPU资源，因为消耗资源越多的代码路径，被采样到的概率越大。

能够探测你指定的函数，并且在满足条件的时候打印指定格式的追踪消息。

命令格式：

trace [-h] [-b BUFFER_PAGES] [-p PID] [-L TID] [-v] [-Z STRING_SIZE] [-S] [-M MAX_EVENTS] [-t] 
      [-u] [-T] [-C] [-c CGROUP_PATH] [-n NAME] [-f MSG_FILTER] [-B] [-s SYM_FILE_LIST] [-K] [-U] [-a]
             [-I header]
             # 探针规格定义
             probe [probe ...]

选项：

perf_events 环缓冲占用的页数量，默认64
-p PID  追踪特定的进程
-L TID 追踪特定的线程
-v 执行前打印生成的BPF代码
-S 包含trace程序自身的栈追踪，默认排除
-M 退出前允许的最大事件数量
-t 打印时间戳信息
-t -u 打印UNIX时间戳
-T 打印时间
-c  cgroup路径
-n 仅仅打印进程名包含该选项指定字符串的进程
-f 仅仅打印消息包含该选项指定字符串的事件
-B 运行对二进制值调用STRCMP
-s 逗号分割的符号文件，用于栈的符号解析
-K 输出内核栈追踪
-U 输出用户栈追踪
-a 在栈中打印虚拟地址
-I 额外包含在BPF程序中的头文件地址

示例：

# 追踪内核的发生的do_sys_open函数调用
trace do_sys_open

# 追踪open系统调用，并打印打开的文件名
#     ::do_sys_open (没有前缀)表示你需要一个entry probe
#                  格式化为字符串
#                        打印第二个参数
trace 'do_sys_open "%s", arg2'

# 追踪进程名包含main的进程的do_sys_open调用
trace 'do_sys_open "%s", arg2' -n main

# 追踪打开文件名包含config的进程的do_sys_open调用
trace 'do_sys_open "%s", arg2' -f config

# 追踪do_sys_open调用，并打印返回值
# 前缀 r 用来定义一个return probe，关键字retval代表函数返回值
trace 'r::do_sys_open "%llx", retval'

# 追踪内核函数kfree_skb的0x12偏移量的指令
trace kfree_skb+0x12

# 追踪读取超过20000bytes的sys_read系统调用
# 注意：在4.17+，系统调用函数发生了重命名，例如 sys_read被重命名为 __x64_sys_read
trace 'sys_read (arg3 > 20000) "read %d bytes", arg3'

#        中间这个bash表示包含目标函数的库或者二进制文件的名字。如果不指定二进制
#        文件的绝对路径，则它必须位于PATH中
trace 'r:bash:readline "%s", retval'

# 追踪共享库的导出函数，或者二进制文件导入的函数
trace'r:/usr/lib64/libtinfo.so:curses_version "Version=%s", retval'

# 追踪标记参数为42的、由libc发起的open调用
#      指定库名时不需要前缀lib
trace 'c:open (arg2 == 42) "%s %d", arg1, arg2'

# 追踪malloc调用，打印分配的内存大小
trace 'c:malloc "size = %d", arg1'

# 追踪通过write调用写到stdout的字节数
trace 'p:c:write (arg1 == 1) "writing %d bytes to STDOUT", arg3'

# 追踪失败的__kmalloc调用，也就是返回值为0的
trace 'r::__kmalloc (retval == 0) "kmalloc failed!"'

# 多个探针可以在单个命令中执行
#               返回值必须cast为int然后再和0比较，因为argN和retval的默认类型是64bit整数
#               可能溢出为负数了
trace 'r:c:read ((int)retval < 0) "read failed: %d", retval' \
        'r:c:write ((int)retval < 0) "write failed: %d", retval' -T

# 该工具也对内核tracepoint提供了基本的支持
# 前缀 t 用来定义一个tracepoint
trace 't:block:block_rq_complete "sectors=%d", args->nr_sector' -T
# 要想知道tracepoint的结构的格式，也就是       args 指针的格式，可以利用工具tplist
tplist -v block:block_rq_complete
#   block:block_rq_complete
#       dev_t dev;
#       sector_t sector;
#       unsigned int nr_sector;
#       int errors;
#       char rwbs[8];

# 越来越多的高层次的库，启用了基于USDT探针的内省支持。这些探针的用法就像内核的tracepoint
# 前缀 u 用来定义一个USDT
#                                %U表示将arg3解析为用户空间符号，类似的%K则解析为内核空间符号
trace 'u:pthread:pthread_create "%U", arg3' -T -C

# Ruby OpenJDK Node等平台，也都支持USDT
# 下面的例子追踪Ruby方法调用，需要Ruby构建时启用配置--enable-dtrace
#                                    类名   方法名
trace 'u:ruby:method__entry "%s.%s", arg1, arg2' -p $(pidof irb) -T

# 根据字符串来过滤
#                打开文件名中包含test.txt
trace 'p:c:open (STRCMP("test.txt", arg1)) "opening %s", arg1' -T

# 通过提供函数签名，来提升可读性
trace 'p:c:open(char *filename) "opening %s", filename'

追踪一个函数，并且打印它的参数汇总信息。

对函数、追踪点、USDT探针进行计数。

显示使用了BPF程序和Map的进程。

打印全局范围内，在bash中执行的所有命令。

追踪对内核函数

cap_capable()

完整的开发文档参考：https://github.com/iovisor/bcc/blob/master/docs/reference_guide.md

要基于BCC开发BPF程序，你可以使用多种编程语言，例如Python、Lua或者CPP。不过，你通常都要在这些编程语言代码中，用字符串嵌入C语言的BPF程序片段。

#include <unistd.h>
#include <fstream>
#include <iostream>
#include <string>

#include "bcc_version.h"
#include "BPF.h"

const std::string BPF_PROGRAM = R"(
int on_sys_clone(void *ctx) {
  bpf_trace_printk("Hello, World! Here I did a sys_clone call!\n");
  return 0;
}
)";

int main() {
  // 此类提供BPF各种操作接口
  ebpf::BPF bpf;
  // 初始化C编写的BPF程序片段
  auto init_res = bpf.init(BPF_PROGRAM);
  if (init_res.code() != 0) {
    std::cerr << init_res.msg() << std::endl;
    return 1;
  }
  // 打开此输入流用于查看BPF程序打印的日志
  std::ifstream pipe("/sys/kernel/debug/tracing/trace_pipe");
  std::string line;
  // 获取系统调用的函数名，4.17+给系统调用函数名加了前缀__x64_，这个函数会自动添加前缀
  std::string clone_fnname = bpf.get_syscall_fnname("clone");

  //                挂钩探针            到此函数        探针的BPF函数名
  auto attach_res = bpf.attach_kprobe(clone_fnname, "on_sys_clone");
  if (attach_res.code() != 0) {
    std::cerr << attach_res.msg() << std::endl;
    return 1;
  }

  std::cout << "Starting HelloWorld with BCC " << LIBBCC_VERSION << std::endl;

  while (true) {
    if (std::getline(pipe, line)) {
      std::cout << line << std::endl;
      // 当pipe中没有更多数据可读，卸载探针
      auto detach_res = bpf.detach_kprobe(clone_fnname);
      if (detach_res.code() != 0) {
        std::cerr << detach_res.msg() << std::endl;
        return 1;
      }
      break;
    } else {
      std::cout << "Waiting for a sys_clone event" << std::endl;
      sleep(1);
    }
  }

  return 0;
}

from bcc import BPF

# This may not work for 4.17 on x64, you need replace kprobe__sys_clone with kprobe____x64_sys_clone
BPF(text='int kprobe__sys_clone(void *ctx) { bpf_trace_printk("Hello, World!\\n"); return 0; }').trace_print()

类似C++的ebpf::BPF类，Python中的BPF类提供了BPF操作的各种接口。

text参数是需要执行的C语言编写的BPF程序。

kprobe__sys_clone()

kprobe__

Kprobe接收一个

ctx

void*

函数bpf_trace_printk()打开公共的内核调试追踪管道（kernel debug trace pipe）并写入消息，也就是/sys/kernel/debug/tracing/trace_pipe。此管道是公共的，也就是所有BPF程序都可能写入消息，导致输出混乱。此外此管道性能较差，因此可以考虑BPF_PERF_OUTPUT()。

trace_print()

b = BPF(text=prog)
# ...
# 获得字段元组，而非字符串
(task, pid, cpu, flags, ts, msg) = b.trace_fields()

// b = BPF(text="""
#include <uapi/linux/ptrace.h>

// 定义一个哈希表，使用默认的键值类型u64
BPF_HASH(last);

int do_trace(struct pt_regs *ctx) {
    u64 ts, *tsp, delta, key = 0;

    // 查找键值
    tsp = last.lookup(&key);
    if (tsp != NULL) {
        //      此助手函数返回当前纳秒数
        delta = bpf_ktime_get_ns() - *tsp;
        if (delta < 1000000000) {
            // output if time is less than 1 second
            bpf_trace_printk("%d\\n", delta / 1000000);
        }
        // 删除键值
        last.delete(&key);
    }

    ts = bpf_ktime_get_ns();
    // 更新键值
    last.update(&key, &ts);
    return 0;
}
// """)
// b.attach_kprobe(event=b.get_syscall_fnname("sync"), fn_name="do_trace")

由于bpf_trace_printk()性能较差，不适合在生产环境中使用。perfbuf可以作为其代替品。perfbuf本质上是BPF_MAP_TYPE_PERF_EVENT_ARRAY类型的Map。

使用BCC时，可以直接调用

BPF_PERF_OUTPUT()

from bcc import BPF
# prog = """

#include <linux/sched.h>

// 定义一个结构，作为输出的“事件”
struct data_t {
    u32 pid;
    u64 ts;
    char comm[TASK_COMM_LEN];
};
// 定义名为events的perfbuf
BPF_PERF_OUTPUT(events);

int hello(struct pt_regs *ctx) {
    struct data_t data = {};
    // 当前进程ID（内核角度的PID，对应用户空间的Thread ID），此ID存放在低32bit
    // 当前线程组ID（内核角度的Thread Group ID，对应用户空间的PID），此ID存放在高32bit
    // 这里直接赋值给u32，导致高32bit丢弃，存储线程ID
    // 对于多线程程序，它的所有线程共享TGID，如果需要区分不同线程，应当使用PID
    data.pid = bpf_get_current_pid_tgid();
    // 时间戳
    data.ts = bpf_ktime_get_ns();
    // 当前进程名
    bpf_get_current_comm(&data.comm, sizeof(data.comm));

    // 提交事件到用户空间
    events.perf_submit(ctx, &data, sizeof(data));

    return 0;
} 

# """

# 加载并挂钩BPF程序
b = BPF(text=prog)
b.attach_kprobe(event=b.get_syscall_fnname("clone"), fn_name="hello")

# header
print("%-18s %-16s %-6s %s" % ("TIME(s)", "COMM", "PID", "MESSAGE"))

start = 0
# 处理事件的回调函数
def print_event(cpu, data, size):
    global start
    #       访问perfbuf 转换事件（data）为Python对象
    event = b["events"].event(data)
    if start == 0:
            start = event.ts
    time_s = (float(event.ts - start)) / 1000000000
    print("%-18.9f %-16s %-6d %s" % (time_s, event.comm, event.pid,
        "Hello, perf_output!"))

# 打开perfbuf，设置回调函数
b["events"].open_perf_buffer(print_event)
while 1:
    # 阻塞式的拉取事件
    b.perf_buffer_poll()

from __future__ import print_function
from bcc import BPF
from time import sleep

# b = BPF(text="""

#include <uapi/linux/ptrace.h>
#include <linux/blkdev.h>

// 声明一个直方图Map
BPF_HISTOGRAM(dist);
//  kprobe__开头的，表示是Kprobe，后面的blk_account_io_done就是目标函数
int kprobe__blk_account_io_done(struct pt_regs *ctx, struct request *req)
{
	// 让直方图的指定索引上的计数增加
	// 将块IO数据长度取2为底的对数，作为索引值。这表示进行2^的桶分布
	// 打个比方，当前操作字节数为64KB，取对数得到6，因此增加下面的第6个桶的计数

	//      kbytes          : count     distribution
	//        0 -> 1        : 3        |                                      |
	//        2 -> 3        : 0        |                                      |
	//        4 -> 7        : 211      |**********                            |
	//        8 -> 15       : 0        |                                      |
	//       16 -> 31       : 0        |                                      |
	//       32 -> 63       : 0        |                                      |
	//       64 -> 127      : 1        |                                      |
	//      128 -> 255      : 800      |**************************************|
	dist.increment(bpf_log2l(req->__data_len / 1024));
	return 0;
}

# """)

# header
print("Tracing... Hit Ctrl-C to end.")

# trace until Ctrl-C
try:
	sleep(99999999)
except KeyboardInterrupt:
	print()

# output
b["dist"].print_log2_hist("kbytes")

b = BPF(src_file = "vfsreadlat.c")

要运行tracepoint BPF程序，你需要Linux内核4.7+版本。

// instrument内核中追踪带年random:urandom_read。追踪点具有稳定的API，应当尽可能使用追踪点
// 而不是kprobes
TRACEPOINT_PROBE(random, urandom_read) {
    // args is from /sys/kernel/debug/tracing/events/random/urandom_read/format
    bpf_trace_printk("%d\\n", args->got_bits);
    return 0;
}

所有可用的追踪点可以通过下面的命令获得：

tplist
# 或者
perf list

追踪点可用参数可以通过下面的命令获得：

tplist -v random:urandom_read
# random:urandom_read
#     int got_bits;
#     int pool_left;
#     int input_left;

下面的例子，追踪内核函数：

#include <uapi/linux/ptrace.h>
#include <linux/sched.h>

struct key_t {
    u32 prev_pid;
    u32 curr_pid;
};

BPF_HASH(stats, struct key_t, u64, 1024);
//                                   第二个参数开始，对应被探测的内核函数的参数
int count_sched(struct pt_regs *ctx, struct task_struct *prev) {
    struct key_t key = {};
    u64 zero = 0, *val;

    key.curr_pid = bpf_get_current_pid_tgid();
    key.prev_pid = prev->pid;

    // 等价于 stats.increment(key)
    val = stats.lookup_or_try_init(&key, &zero);
    if (val) {
      (*val)++;
    }
    return 0;
}

注册探针：

b.attach_kprobe(event="finish_task_switch", fn_name="count_sched")

需要注意的一点是，你可以在探针的参数列表中，将被探测函数的参数列出来，并访问。 finish_task_switch的签名：

static struct rq *finish_task_switch(struct task_struct *prev)
	__releases(rq->lock);

因此在探针中我们可以访问prev参数，代表被切换出去的进程。

下面的例子追踪用户空间函数strlen()。

#include <uapi/linux/ptrace.h>

struct key_t {
    char c[80];
};
BPF_HASH(counts, struct key_t);

int count(struct pt_regs *ctx) {
    // 从上下文中读取strlen()的第一个参数
    if (!PT_REGS_PARM1(ctx))
        return 0;

    struct key_t key = {};
    u64 zero = 0, *val;

    // 将参数存入结构
    bpf_probe_read_user(&key.c, sizeof(key.c), (void *)PT_REGS_PARM1(ctx));
    // 将结构存入Map，如果没有对应的key则初始化
    val = counts.lookup_or_try_init(&key, &zero);
    // 增加计数
    if (val) {
      (*val)++;
    }
    return 0;
};

# 挂钩到         库c      的strlen函数   钩子函数为count
b.attach_uprobe(name="c", sym="strlen", fn_name="count")

USDT即用户静态定义的追踪点（user statically-defined tracing point），相当于tracepoint的用户态版本。很多流行的软件、框架都预置了USDT。

#include <uapi/linux/ptrace.h>
int do_trace(struct pt_regs *ctx) {
    uint64_t addr;
    char path[128]={0};
    // 读取USDT探针的第6个参数，到addr变量
    bpf_usdt_readarg(6, ctx, &addr);
    // 将addr作为指针看待，并且从它所在位置读取最多128字节的字符串
    bpf_probe_read_user(&path, sizeof(path), (void *)addr);
    bpf_trace_printk("path:%s\\n", path);
    return 0;
};

# 为指定的PID初始化USDT追踪
u = USDT(pid=int(pid))
# 挂钩do_trace到追踪点http__server__request
u.enable_probe(probe="http__server__request", fn_name="do_trace")

# 初始化BPF
b = BPF(text=bpf_text, usdt_contexts=[u])

# 在Python程序中定义一个内核常量，不需要给出头文件
REQ_WRITE = 1		# from include/linux/blk_types.h

# 加载BPF程序
# b = BPF(text=""" 

#include <uapi/linux/ptrace.h>
#include <linux/blkdev.h>

// 哈希表        键的类型（值类型是默认的u64）
BPF_HASH(start, struct request *);

// KProbe的参数pt_regs，包含registers、BPF上下文
//                                    struct request *req是目标函数blk_start_request的第一个参数
void trace_start(struct pt_regs *ctx, struct request *req) {
	u64 ts = bpf_ktime_get_ns();
        // 直接使用请求参数的指针作为键，在追踪程序中这很常见。因为任何两个结构都不会有相同的地址
        // 可以安全的作为唯一键（注意内存被释放并重用的情况）
	start.update(&req, &ts);
}

void trace_completion(struct pt_regs *ctx, struct request *req) {
	u64 *tsp, delta;
        // 查找先前记录的时间戳
	tsp = start.lookup(&req);
	if (tsp != 0) {
		// 获取消耗的时间
		delta = bpf_ktime_get_ns() - *tsp;
		// 打印本次块IO操作的信息
		//                           直接访问结构字段，BCC会自动将其转换为bpf_probe_read_kernel()调用
		//                           某些情况下BCC无法处理复杂的解引用操作，你可以手工调用该助手函数
		bpf_trace_printk("%d %x %d\\n", req->__data_len,
		    req->cmd_flags, delta / 1000);
		start.delete(&req);
	}
}
 

# """)
# 函数 void blk_start_request ( struct request * req); 开始请求驱动来处理块IO请求
b.attach_kprobe(event="blk_start_request", fn_name="trace_start")
# 函数 void blk_mq_start_request(struct request *rq); 高IOPS下Linux的块设备层形成了瓶颈
# 因此多核心系统下，3.13+添加的Multi queue特性可以减少块设备层的性能影响。传统块设备层有能力
# 处理万级别的IOPS，但是随着SSD这样的高性能设备的出现，其出现能力瓶颈。Multi queue的主要思想
# 是，为每个CPU核心设置一个请求队列，均衡核之间的负载，减少对请求队列的锁竞争
b.attach_kprobe(event="blk_mq_start_request", fn_name="trace_start")
# 函数 void blk_account_io_done(struct request *req, u64 now); 在块设备IO完成后调用
# 此函数优于blk_account_io_completion()，后者可能在请求部分完成的情况下调用，调用可能发生多次，
# 这种现象会发生在loop设备/老的SCSI上
b.attach_kprobe(event="blk_account_io_done", fn_name="trace_completion")

可以使用具有稳定接口的追踪点block:block_rq_issue、block:block_rq_complete代替上述Kprobe。

所有统计延迟的监控程序，都是选择适当的键，然后在entry/return钩子中进行计时：

#include <uapi/linux/ptrace.h>

BPF_HASH(start, u32);
BPF_HISTOGRAM(dist);

int do_entry(struct pt_regs *ctx)
{
	u32 pid;
	u64 ts, *val;

	pid = bpf_get_current_pid_tgid();
	ts = bpf_ktime_get_ns();
	// 记录开始时间
	start.update(&pid, &ts);
	return 0;
}

int do_return(struct pt_regs *ctx)
{
	u32 pid;
	u64 *tsp, delta;

	pid = bpf_get_current_pid_tgid();
	tsp = start.lookup(&pid);

	if (tsp != 0) {
		// 计算耗时
		delta = bpf_ktime_get_ns() - *tsp;
		// 更新桶计数
		dist.increment(bpf_log2l(delta / 1000));
		start.delete(&pid);
	}

	return 0;
}

# 从文件中加载BPF程序
b = BPF(src_file = "vfsreadlat.c")
# 挂钩的内核函数是vfs_read
b.attach_kprobe(event="vfs_read", fn_name="do_entry")
b.attach_kretprobe(event="vfs_read", fn_name="do_return")

The post 基于BCC进行性能追踪 appeared first on 绿色记忆.

Sysdig是一个开源的系统性能分析工具，可以实现strace、tcpdump、lsof、top、iftop等工具所具有的功能。

如果需要源代码级别的、通用剖析工具，可以参考：利用perf剖析Linux应用程序。

# CentOS 7
rpm --import https://s3.amazonaws.com/download.draios.com/DRAIOS-GPG-KEY.public
curl -s -o /etc/yum.repos.d/draios.repo http://download.draios.com/stable/rpm/draios.repo
# yum update
yum -y install epel-release

yum install kernel-devel-$(uname -r)
yum install sysdig
/usr/lib/dkms/dkms_autoinstaller start
sysdig-probe-loader

-c 运行指定的chisel，如果chisel需要参数，则必须用--chisel=chiselname chiselargs形式
-cl 列出可用的chisel，从./chisels, ~/.chisels,/usr/share/sysdig/chisels搜索
-M 在指定秒数之后停止收集
-n 在获取指定数量的事件之后停止收集
-S 在捕获结束，例如列出top事件之后，打印汇总摘要
-s 捕获IO缓冲的前N字节，默认80

不加任何参数调用，每行显示一个捕获的事件，不断刷新。输出格式：

# 事件号 发生事件          CPU号   进程名(PID） 事件方向
#                                             事件类型 事件参数
1462218 16:40:38.068514659 3 <NA> (2941270) > switch next=2941697(sysdig) pgft_maj=0 pgft_min=0 vm_size=0 vm_rss=0 vm_swap=0                                                             
1462220 16:40:38.068515560 6 java (2556857) > futex addr=7F3B3888C598 op=129(FUTEX_PRIVATE_FLAG|FUTEX_WAKE) val=1                                                                        
1462222 16:40:38.068515997 5 java (2557004) > futex addr=7F3AEC01C894 op=137(FUTEX_PRIVATE_FLAG|FUTEX_WAIT_BITSET) val=1                                                                 
1462224 16:40:38.068516460 6 java (2556857) < futex res=0

可以将结果输出到文件而非控制台：

sysdig -w result.dump

sysdig -r result.dump

可以使用过滤器对sysdig输出进行过滤，过滤器支持 =、!=、contains等操作符

下面的命令列出可用的过滤器：

sysdig -l

----------------------
Field Class: fd

fd.num          # 文件描述符号
fd.type         # 文件描述符类型，支持的值：'file', 'directory', 'ipv4', 'ipv6', 'unix',
                # 'pipe', 'event', 'signalfd', 'eventpoll', 'inotify', 'signal fd'
fd.typechar     # 文件描述符类型简写，支持的值：f                 4       6       u
                #  p      e         s           l            i
                # o表示未知
fd.name         # 文件描述符全名，对于文件，即完整路径；对于套接字，即连接元组
fd.directory    # 文件描述符是文件，且它必须位于此目录下
fd.filename     # 文件描述符是文件，且它的basename是此值
fd.ip           # 匹配客户端或服务器IP地址
fd.cip          # 匹配客户端IP地址
fd.sip          # 匹配服务器IP地址
fd.lip          # 匹配本地地址
fd.rip          # 匹配远程地址
fd.port         # 匹配客户端或服务器端口
fd.cport        # 对于TCP/UDP，客户端端口
fd.sport        # 对于TCP/UDP，客户端端口
fd.lport        # 对于TCP/UDP，本地端口
fd.rport        # 对于TCP/UDP，远程端口
fd.l4proto      # 套接字协议，可选 'tcp', 'udp', 'icmp' or 'raw'
fd.sockfamily   # 套接字家族，可选 'ip' or 'unix'
fd.is_server    # 指定为true则用于套接字的进程必须是服务器端
fd.uid          # FD的唯一标识
fd.containername
                # container ID + FD name
fd.containerdirectory
                # container ID + directory name
fd.proto        # FD的协议
fd.cproto       # 对于TCP/UDP，客户端协议
fd.sproto       # 对于TCP/UDP，服务器协议
fd.lproto       # 对于TCP/UDP，本地协议
fd.rproto       # 对于TCP/UDP，远程协议
fd.net          # IP网络
fd.cnet         
fd.snet         
fd.lnet         
fd.rnet         
fd.connected    # 对于TCP/UDP，设置为true则仅仅匹配已连接的套接字

----------------------
Field Class: process

proc.pid        # 生成事件的进程的ID
proc.exe        # 第一个命令行参数，通常是可执行文件名
proc.name       # 生成事件的可执行文件的名称
proc.args       # 生成事件的进程的命令行参数
proc.env        # 环境变量 
proc.cmdline    # 完整命令行，也就是 proc.name + proc.args
proc.exeline    # 完整命令行，也就是 proc.exe + proc.args
proc.cwd        # 当前工作目录
proc.nthreads   # 进程包括的线程数量
proc.nchilds    # 进程包括的子线程数量（除去主线程）
proc.ppid       # 父进程ID
proc.pname      # 父进程名称
proc.pcmdline   # 父进程的cmdline
proc.apid       # 某个祖先进程的ID
proc.aname      # 某个祖先进程的名称
proc.loginshellid
                # 登陆Shell ID
proc.duration   # 进程已经启动的纳秒
proc.fdopencount
                # 进程打开的文件描述符数量
proc.fdlimit    # 进程能够打开的文件描述符数量
proc.fdusage    # 打开/最大文件描述符比率
proc.vmsize     # 进程虚拟内存大小，单位KB
proc.vmrss      # 驻留内存大小
proc.vmswap     # 交换到磁盘的内存大小
thread.pfmajor  # 进程启动以来主页面错误次数
thread.pfminor  # 进程启动以来次页面错误次数
thread.tid      # 线程ID
thread.ismain   # 如果指定为true，生成事件的线程必须是主线程
thread.exectime # 最后被调度的线程消耗的CPU纳秒数
thread.totexectime
                # 从捕获开始，当前线程使用的CPU纳秒总数
thread.cgroups  # 线程所属的Cgroup，聚合为单个字符串
thread.cgroup   # 线程所属的某个Cgroup子系统
thread.vtid     # 从产生事件的线程自己的PID命名空间看到的，自己的PID
proc.vpid       # 从产生事件的进程自己的PID命名空间看到的，自己的PID
thread.cpu      # 最近一秒消耗的CPU时间
thread.cpu.user # 最近一秒消耗的CPU时间（用户态）
thread.cpu.system
                # 最近一秒消耗的CPU时间（内核态）
thread.vmsize   # 对于主线程，即虚拟内存大小，对于非主线程，为0
proc.sid        # 会话ID
proc.sname      # 会话名称
proc.tty        # 进程的控制终端，0为无控制终端的进程
proc.exepath    # 可执行文件的完整路径
proc.vpgid      # 从产生事件的进程自己的PID命名空间看到的，自己的进程组ID

----------------------
Field Class: evt

evt.num         # 事件编号
evt.time        # 事件时间戳，包含纳秒部分
evt.time.s      # 事件时间戳，不包含纳秒
evt.datetime    # 事件时间戳，包含日期部分
evt.rawtime     # 原始时间戳，19700101到现在的纳秒数
evt.rawtime.s   # 原始时间戳，19700101到现在的秒数
evt.rawtime.ns  # 原始时间戳，小数部分（纳秒部分）
evt.reltime     # 从捕获到发生事件时流逝的时间
evt.reltime.s  
evt.reltime.ns  
evt.latency     # 配对的enter/exit事件的延迟，纳秒
evt.latency.s   
evt.latency.ns  
evt.latency.human
                # 可读格式，例如10.3ms
evt.deltatime   # 当前事件和上一个事件之间的延迟
evt.deltatime.s 
evt.deltatime.ns
evt.dir         # 事件方向，>为enter事件，<为exit事件
evt.type        # 事件（类型的）名称，例如open
evt.type.is     # evt.type.is.open匹配所有open事件
syscall.type    # 对于系统调用事件，指定系统调用名称，例如open
evt.category    # 事件分类，例如file表示文件操作包括open/close，net表示网络操作
                # memory表示mmap/brk等操作
evt.cpu         # 事件所在的CPU序号
evt.args        # 聚合为字符串的事件参数
evt.arg         # 单个事件参数，使用参数名或序号，例如evt.arg.fd或'evt.arg[0]
evt.res         # 事件结果字符串，如果成功SUCCESS，否则是错误码字符串，例如ENOENT 
evt.failed      # 如果true匹配失败事件
evt.is_io       # 匹配读写FD的事件，例如 read(), send, recvfrom()
evt.is_io_read  
evt.is_io_write 
evt.io_dir      # IO方向，r或w
evt.is_wait     # 如果true则匹配那些导致线程等待的事件，例如sleep(), select(), poll()
evt.wait_latency
                # 等待事件返回（exit）消耗的时间阈值
evt.is_syslog   # 事件是否是写入syslog
evt.is_open_read
                # 如果为true，匹配打开以进行读的open/openat事件
evt.is_open_write
                # 如果为true，匹配打开以进行写的open/openat事件

----------------------
Field Class: user

user.uid        # 用户ID
user.name       # 用户名称
user.homedir    # 家目录
user.shell      # 用户的Shell
user.loginuid   # 审计用户ID
user.loginname  # 审计用户名

----------------------
Field Class: group

group.gid       # 组ID
group.name      # 组名称

----------------------
Field Class: container

container.id    # 容器ID
container.name  # 容器名称
container.image # 容器镜像名称
container.image.id
                # 容器镜像ID
container.type  # 容器类型，例如docker, rkt
container.privileged
                # true则匹配运行在特权模式的容器
container.image.repository
container.image.tag
container.image.digest

----------------------
Field Class: k8s

k8s.pod.name    # Pod名称
k8s.pod.id      # Pod标识符
k8s.pod.label   # Pod的标签，例如k8s.pod.label.foo
k8s.pod.labels  # 逗号分隔的多个Pod标签
k8s.rc.name     # 复制控制器
k8s.rc.id       
k8s.rc.label    
k8s.rc.labels   
k8s.svc.name    # 服务
k8s.svc.id      
k8s.svc.label   
k8s.svc.labels  
k8s.ns.name     # 命名空间
k8s.ns.id       
k8s.ns.label    
k8s.ns.labels
k8s.rs.name     # 复制集
k8s.rs.id      
k8s.rs.label   
k8s.rs.labels   
                
k8s.deployment.name
                # Deployment
k8s.deployment.id
k8s.deployment.label
k8s.deployment.labels

过滤特定进程产生的事件： 

# 仅仅捕获sshd产生的事件
sysdig proc.name=sshd

# 读取Dump，仅仅显示mysqld产生的事件
sysdig -r result.dump proc.name=mysqld

Sysdig中的chisels是一小段Lua脚本，用于分析sysdig事件流。Chisels支持：

1. 实时分析：每秒刷新一次
2. 离线分析：会打印总体的汇总信息

执行下面的命令列出可用的Chisels：
 

sysdig -cl

Category: Application
---------------------
httplog         # HTTP请求日志
httptop         # HTTP请求TOP
memcachelog     # memcache请求日志

Category: CPU Usage
-------------------
spectrogram     # OS延迟的可视化直方图
subsecoffset    # 
topcontainers_cpu
                # CPU占用最高的容器
topprocs_cpu    # CPU占用最高的进程

Category: Errors
----------------
topcontainers_error
                # 错误最多的容器
topfiles_errors # 错误最多的文件
topprocs_errors # 错误最多的进程

Category: I/O
-------------
echo_fds        # 打印进程读写的文件
fdbytes_by      # IO字节数，根据一个任意的过滤器字段进行聚合
fdcount_by      # FD计数，根据一个任意的过滤器字段进行聚合
fdtime_by       # FD时间
iobytes         # 任何类型的FD的IO字节数总和
iobytes_file    # 文件IO字节数总和
spy_file        # 回响任何进程对所有文件进行的任何读写，可选的，你可以提供一个文件名，这样只会拦截
                # 单个文件上发生的读写
stderr          # 打印进程的标准错误
stdin           # 打印进程的标准输入
stdout          # 打印进程的标准输出
topcontainers_file
                # 读写磁盘字节数最多的容器
topfiles_bytes  # 被读写字节数最多的文件
topfiles_time   # 被访问时间最长的文件
topprocs_file   # 读写磁盘字节数最多的进程

Category: Logs
--------------
spy_logs        # 回响任何进程对任何日志文件执行的写入
spy_syslog      # 打印任何写入到syslog的消息

Category: Misc
--------------
around          # 在指定过滤器匹配时，输出指定事件范围附近的事件

Category: Net
-------------
iobytes_net     # 显示总和网络IO字节数
spy_ip          # 显示和指定IP地址的数据交换情况
spy_port        # 显示和指定端口的数据交换情况
topconns        # IO字节数最多的网络链接
topcontainers_net
                # 导致网络IO最多的容器
topports_server # 读写字节数最多的TCP/UDP端口
topprocs_net    # 导致网络IO最多的进程

Category: Performance
---------------------
bottlenecks     # 最缓慢的系统调用
fileslower      # 跟踪缓慢的文件IO
netlower        # 跟踪缓慢的网络IO
proc_exec_time  # 显示进程执行时间
scallslower     # 跟踪缓慢的系统调用
topscalls       # 调用次数最多的系统调用
topscalls_time  # 消耗时间最多的系统调用

Category: Security
------------------
list_login_shells
                # 列出登陆Shell的ID
shellshock_detect
                # 打印 shellshock攻击
spy_users       # 显示交互式的用户活动

Category: System State
----------------------
lscontainers    # 列出运行中的荣iq
lsof            # 列出（可过滤）打开的文件描述符
netstat         # 列出（可过滤）打开的网络链接
ps              # 列出（可过滤）运行中的进程

显示使用网络带宽最多的进程： 

sysdig -c topprocs_net

查看网络IO最高的进程： 

sysdig -c topprocs_net                                                                                                                                         
# Bytes               Process             PID                                                                                                                                              
# --------------------------------------------------------------------------------                                                                                                         
# 38.48KB             msgr-worker-1       198488                                                                                                                                           
# 24.36KB             msgr-worker-0       198488                                                                                                                                           
# 8.12KB              msgr-worker-2       198488                                                                                                                                           
# 76B                 bird                3951084                                                                                                                                          
# 52B                 zabbix_agentd       5930                                                                                                                                             
 #31B                 zabbix_agentd       5931

打印和目标主机之间的数据交换： 

# 以二进制形式打印
sysdig -s2000 -X -c echo_fds fd.cip=10.5.39.41
# 以ASCII形式打印
sysdig -s2000 -A -c echo_fds fd.cip=192.168.0.1

最繁忙服务器端口，按当前已建立连接数：

# 按服务器端口分组
sysdig -c fdcount_by fd.sport "evt.type=accept"

最繁忙客户端地址，按收发字节数：

sysdig -c fdbytes_by fd.cip

列出不是发往Apache的入站请求： 

sysdig -p "%proc.name %fd.name" "evt.type=accept and proc.name!=httpd"

捕获打开特定文件的进程： 

# 针对/var/log文件的事件
sysdig fd.name=/var/log
# 事件参数fd中包含/var/log的事件
sysdig fd.name contains /var/log
# 7227884 16:52:37.116806685 4 svlogd (5880) > write fd=6(<f>/var/log/calico/libnetwork/current) size=50 
# 7227885 16:52:37.116816800 4 svlogd (5880) < write res=50 data=./run: exec: line 3: libnetwork-plugin: not found.

下面的例子，显示被读写字节数最多的文件（瞬时）：

sysdig -c topfiles_bytes

# Bytes               Filename                                                                                                                                                             
# --------------------------------------------------------------------------------                                                                                                         
# 2.53KB              /etc/hosts                                                                                                                                                           
# 585B                /sys/fs/cgroup/memory/kubepods/besteffort/pod56e20dda-38bf-11e9-99bd-44a8421fdcc8/memory.stat                                                                        
# 563B                /sys/fs/cgroup/memory/kubepods/besteffort/memory.stat                                                                                                                
# 116B                /sys/fs/cgroup/cpu,cpuacct/kubepods/besteffort/cpuacct.usage_percpu

联用过滤器，仅仅显示/root下读写字节数最多的文件（瞬时）：

sysdig -c topfiles_bytes "fd.name contains /root"

联用过滤器，仅仅显示admin用户读写字节数最多的文件（瞬时）： 

sysdig -c topfiles_bytes "user.name=admin" 

显示延迟超过1ms的IO调用： 

sysdig -c fileslower 1
# evt.datetime            proc.name    evt.type LATENCY(ms)  fd.name
# ----------------------- ------------ -------- ------------ -----------------------------------------
# 2019-03-25 11:15:54.119 node_exporte read               75 /host/sys/fs/xfs/sda2/stats/stats

根据FD类型汇总IO数据量：

sysdig -r t.scap -c fdbytes_by fd.type

# Bytes     fd.type
# ------------------------------
# 485.00M   file
# 4.63M     unix
# 509.92KB  pipe
# 99.83KB   ipv4
# 53.79KB   event
# 3.08KB    inotify

根据目录汇总IO数据量，仅仅考虑文件IO： 

sysdig -r t.scap -c fdbytes_by fd.directory "fd.type=file"

# Bytes     fd.directory
# ------------------------------
# 101.89M   /tmp/
# 90.26M    /root/.ccache/tmp/
# 85.75M    /usr/include/c++/4.7.2/bits/
# 24.74M    /usr/include/c++/4.7.2/

在特定目录下，汇总每个文件的IO数据量：  

sysdig -r t.scap -c fdbytes_by fd.filename "fd.directory=/tmp/"

# Bytes     fd.filename
# ------------------------------
# 13.64M    ccJvb4Mi.s
# 9.33M     cc4pbJkV.s
# 6.72M     ccx9zir6.s

发现导致特定目录下文件IO的进程： 

# 根据进程名聚合
                                         # 逻辑与：IO的目标是/tmp/*.s文件
sysdig -r t.scap -c fdbytes_by proc.name "fd.directory=/tmp/ and fd.filename contains .s"

# Bytes     proc.name
# ------------------------------
# 50.57M    as
# 49.03M    cc1plus
# 1.54M     cc1
# 1B        httpd

发现针对特定文件IO的调用栈： 

sysdig -A -r t.scap -c echo_fds "fd.filename=ccJvb4Mi.s"

# ------ Write 4.00KB to /tmp/ccJvb4Mi.s
# .file"chisel.cpp"
# .text
# .Ltext0:
# .section.text._ZNSt9exceptionC2Ev,"axG",@p 

# CPU用量最大的进程
sysdig -pc -c topprocs_cpu
# 网络带宽用量最大的进程
sysdig -pc -c topprocs_net 
# 文件IO字节数最大
sysdig -pc -c topfiles_bytes
# 网络连接数最高
sysdig -pc -c topconns 

sysdig的图形化用户接口，类似于top或htop，但是功能要强大的多：

1. 支持实时分析，也支持分析sysdig跟踪文件。跟踪文件可以来自其它机器
2. 支持CPU、内存、磁盘IO、网络IO等多方面指标的详细分析
3. 支持跟踪进程、文件、网络连接的IO活动
4. 可以钻取到进程、文件、网络连接
5. 支持sysdig的过滤语法
6. 支持容器和K8S

csysdig基于view，每个view是一小段Lua脚本，负责收集指标并展示在屏幕上

apt-get install sysdig

 -d 刷新间隔，默认2000
-pc  容器支持，显示额外的容器相关的字段
-k 启用K8S支持，指定API Server的URL，可用环境变量SYSDIG_K8S_API代替
-K 使用指定的凭证来访问K8S，可用环境变量SYSDIG_K8S_API_CERT代替
-N 不把端口号转换为名称
-r 读取跟踪文件

1. 不使用参数调用该命令，执行实时分析；使用-r来分析跟踪文件
2. 按F2切换view
3. Enter可以钻取，Backspace可以退回
4. 按F5可以显示选中条目的IO活动
5. 按F6可以看到选中条目的sysdig事件

你可以钻取、上卷，快捷键分别为Enter、Backspace。例如你可以从进程钻取到线程，在不同的钻取级别，你都可以切换、查看其它view，非常强大

1. 进程视图：k杀死进程
2. 容器视图：b打开Shell

以系统调用为例，颜色越靠近红色，说明那个耗时区间的系统调用越多： 

F2选择视图时，右侧会给出每个字段的含义

The post 使用Sysdig进行系统性能分析 appeared first on 绿色记忆.

剖析（Profiling）是一种有效的、细粒度的软件性能检查手段，大部分编程语言的生态圈都有各种性能剖析工具。本文的讨论内容与具体编程语言无关，而关注在Linux系统上对应用程序的性能进行剖析。

Linux内核实现了非常有价值的性能分析基础设施（perf infrastructure），可以用于剖析各种CPU或软件事件。这一功能由perf_events接口暴露，并提供

perf

1. 为什么内核使用太多的CPU，哪些代码使用了这些CPU时间
2. 什么代码导致CPU二级缓存不命中
3. CPU是否因内存IO而卡顿
4. 什么代码在分配内存，分配了多少
5. 什么触发了TCP重传
6. 某个内核函数是否被频繁调用
7. 线程离开CPU的原因 

perf_events是内核2.6+的一部分，用户空间工具perf在包linux-tools-common中，需要安装才能使用。要想从剖析中获得更多内核相关信息，你需要符号（Symbol）和栈追踪，这可能需要安装额外的包，甚至使用特定选项重新编译你的内核。剖析用户空间代码时，也要求目标应用程序的调试信息（符号表）被保留。

perf_events有三种工作模式：

1. counting，在内核上下文对各种指标进行计数
2. sampling，对事件进行采样，并将性能数据存放到内核缓冲，然后异步的写入到perf.data
3. bpf，4.4版本内核引入的新特性，允许在内核中执行一段用户自定义的代码，以执行高效的过滤、汇总

perf_events的采样是基于事件进行的。采样的周期以事件的数量来表示，而非基于时间。当目标事件计数溢出指定的数值，则产生一个采样。

样本中包含的信息取决于用户和工具指定的度量类型，但是最重要的信息是指令指针（instruction pointer），也就是程序被中断时所处的位置。

这种基于中断的采样，在现代处理器上存在刹车效应。也就是说，样本中记录的指针，和程序被中断以处理PMU事件时的指令指针，可能相隔数十个指令。

record子命令默认使用cycle事件，类似于定期采样。

perf_events可以捕获的事件类型包括：

1. 硬件事件，来自CPU自己或CPU的PMU（Performance Monitoring Unit，性能监控单元），包含一系列微架构事件例如时钟周期、L1缓存丢失等。具体支持的事件类型取决于CPU型号
2. 软件事件，基于内核计数器的低级事件，例如CPU迁移、上下文切换、Minor Faults、Major Faults（页面错误）
3. 追踪点事件，由内核中的ftrace实现，包括：
   1. 内核追踪点事件，静态的、内核级的追踪点，硬编码到内核
   2. 用户静态定义追踪（USDT），用户态应用程序硬编码的追踪点
   3. 动态追踪，软件可以被动态instrumented，在任何位置创建事件。对于内核软件，使用kprobes框架，对于用户软件，使用uprobes
   4. 定时追踪，以任意频率抓取快照，主要用于CPU剖析，工作机制是定期引发中断

要启用内核动态追踪，需要使用内核编译参数CONFIG_KPROBES=y、CONFIG_KPROBE_EVENTS=y。要追踪基于帧指针的内核栈，需要内核编译参数CONFIG_FRAME_POINTER=y。

要启用用户动态追踪，需要使用内核编译参数CONFIG_UPROBES=y、CONFIG_UPROBE_EVENTS=y

事件有多种表示方式，最简单的是它的字符串表示。引用事件时，可以指定限定符：

# 剖析用户级、内核级的cycle事件
-e cycles
-e cycles:uk
# 仅用户级
-e cycles:u

限定符包括：

perf可以在不同的范围收集性能数据：

1. 单线程（per-thread）：仅仅监控选择的线程。如果线程被调度失去CPU，对它的性能计数暂停，如果线程被调度到其它CPU，计数会存储并恢复，继续在新CPU上进行计数
2. 单进程（ per-process）：进程的所有线程都被监控，计数被汇总
3. 单CPU（ per-cpu）：仅仅监控单颗、或者选定的几颗CPU上的事件
4. 全局（system-wide）：监控所有CPU上的事件

和其它调试工具一样，perf需要符号信息，符号用于将内存地址转换为可读的函数、变量名称。没有符号信息，你会看到0x7ff3c1cddf29这样的HEX代码，无法阅读。

如果需要被剖析的软件通过包管理器安装，你需要找到并安装对应的调试包（可能以-dbgsym为后缀）。如果找不到调试包，可以考虑手工编译。

Java、Node.js等基于虚拟机的语言，在自己的虚拟CPU上执行代码，因而具有自己管理栈和执行函数的方法。

为了通过perf来剖析这类语言的程序，你需要：

1. 对于Java，使用perf-map-agent
2. 对于Node.js，使用命令行选项

   --perf_basic_prof

你可能看不到完整的Java栈，这是因为X86上的Hotspot忽略了帧指针（Frame pointer）。在8u60+版本以后，可以使用-XX:+PreserveFramePointer修复这一问题。

为了方便剖析，编译时尽量保留帧指针，编译器的优化行为可能导致难以调试，但是很多情况下优化掉帧指针是默认行为。

缺少帧指针会导致无法看到完整的调用栈，解决此问题的方法有几种：

1. 使用DWARF（ELF文件通常使用的调试信息格式）信息来Unwind栈
2. 使用LBR（Last Branch Record），这是处理器特性，因此可能不可用
3. 保留帧指针

下面是默认情况下编译（-O2，忽略帧指针）得到的OpenSSH的剖析结果：

57.14%     sshd  libc-2.15.so        [.] connect           
               |
               --- connect
                  |          
                  |--25.00%-- 0x7ff3c1cddf29
                  |          
                  |--25.00%-- 0x7ff3bfe82761
                  |          0x7ff3bfe82b7c
                  |          
                  |--25.00%-- 0x7ff3bfe82dfc
                   --25.00%-- [...]

以

-fno-omit-frame-pointer

100.00%     sshd  libc-2.15.so   [.] __GI___connect_internal
               |
               --- __GI___connect_internal
                  |          
                  |--30.00%-- add_one_listen_addr.isra.0
                  |          add_listen_addr
                  |          fill_default_server_options
                  |          main
                  |          __libc_start_main
                  |          
                  |--20.00%-- __nscd_get_mapping
                  |          __nscd_get_map_ref
                  |          
                  |--20.00%-- __nscd_open_socket
                   --30.00%-- [...]

可以看到符号都显示出来了，另外add_one_listen_addr的祖先帧也显示出来了。 

你需要使用

CONFIG_FRAME_POINTER=y

从内核3.9版本开始，缺失栈指针的问题有个变通的解决方案（对于用户空间的栈）——使用libunwind。libunwind基于dwarf，调用perf时传入--call-graph dwarf即可。

在Ubuntu上可以这样安装：

apt install linux-tools-common

系统可能会提示你安装其它的包，安装即可。

perf支持一系列的子命令：

运行一个命令，并收集性能计数器。

对于任何支持计数的事件，perf都能够在进程执行期间对发生的事件进行计数，计数结果会直接打印在控制台上。

stat子命令可以在线程、进程、CPU、全局级别进行计数。默认情况下进程的所有线程、子进程的计数都被统计在内，可以通过-i选项修改此行为。

参考record子命令。

# 如果不指定-e，则默认收集所有事件的计数器
perf stat [-e <EVENT> | --event=EVENT] [-a] <command>
perf stat [-e <EVENT> | --event=EVENT] [-a] -- <command> [<options>]

# CPU性能计数器
perf stat command

# 详细的CPU性能计数器
perf stat -d command

# 收集指定进程的性能计数，直到Ctrl-C
perf stat -p PID

# 收集整个系统的性能计数，持续5秒
perf stat -a sleep 5
# Performance counter stats for 'system wide':
#      20010.623960      cpu-clock (msec)          #    4.000 CPUs utilized          
#            61,947      context-switches          #    0.003 M/sec                  
#             4,153      cpu-migrations            #    0.208 K/sec                  
#                99      page-faults               #    0.005 K/sec                  
#     5,003,068,069      cycles                    #    0.250 GHz                      (49.96%)
#     2,000,087,622      instructions              #    0.40  insn per cycle           (75.00%)
#       393,183,513      branches                  #   19.649 M/sec                    (75.05%)
#        24,391,051      branch-misses             #    6.20% of all branches          (74.99%)

#       5.003219775 seconds time elapsed


# 指定需要收集的几种计数器，持续10秒
perf stat -e cycles,instructions,cache-references,cache-misses,bus-cycles -a sleep 10

# CPU一级缓存计数器
perf stat -e L1-dcache-loads,L1-dcache-load-misses,L1-dcache-stores command

# TLB计数器
perf stat -e dTLB-loads,dTLB-load-misses,dTLB-prefetch-misses command

# CPU最后一级缓存计数器
perf stat -e LLC-loads,LLC-load-misses,LLC-stores,LLC-prefetches command

# 统计指定进程的系统调用
perf stat -e 'syscalls:sys_enter_*' -p PID

# 统计全局系统调用
perf stat -e 'syscalls:sys_enter_*' -a sleep 5

# 统计调度器相关事件
perf stat -e 'sched:*' -p PID
perf stat -e 'sched:*' -p PID sleep 10

# 统计Ext4相关事件
perf stat -e 'ext4:*' -a sleep 10

# 统计块IO事件
perf stat -e 'block:*' -a sleep 10

# 收集多种事件
perf stat -e cycles,instructions,cache-misses

动态显示执行成本最高的项。

默认情况下以cycles事件采样，样本最高的输出在最顶部。

# 动态显示成本最高的地址和符号，不保存到文件
perf top -F 49
# 动态显示成本最高的命令
perf top -F 49 -ns comm,dso

此命令可以启动一个命令，并对其进行剖析，然后把剖析数据记录到文件（默认perf.data）。按Ctrl - C可以随时结束剖析。

此命令可以在线程、进程、CPU、全局级别进行剖析。

record, report, annotate是一组相关的命名，通常的使用流程是：

1. 在被剖析机器上调用record录制数据
2. 拷贝录制的perf.data，在任意机器上调用report、annotate进行分析

该命令不是记录所有事件，还是进行采样。默认情况下采样基于cycle事件，也就是进行定期采样。

perf_events接口允许通过两种方式描述采样周期：

1. period：事件发生的次数
2. frequency：每秒样本的平均个数

perf默认使用第二种，具体来说对应到-F选项。-F 1000表示1000Hz，也就是每秒平均采样1000个。内核会动态的调整采样周期，以尽量满足需求。

perf record [-e <EVENT> | --event=EVENT] [-l] [-a]    <command>
perf record [-e <EVENT> | --event=EVENT] [-l] [-a] -- <command> [<options>]

perf report -T

-C 0,2-3

# 以99HZ的频率剖析指定的命令，默认情况下工作在Per-thread模式
perf record -F 99 command

# 以99HZ的频率剖析指定的PID
perf record -F 99 -p PID
# 以99HZ的频率剖析指定的PID，持续10秒
perf record -F 99 -p PID sleep 10
# 以99HZ的频率剖析整个系统
perf record -F 99 -ag -- sleep 10

# 基于事件发生次数，而非采样频率来指定采样周期
perf record -e retired_instructions:u -c 2000

# 进行栈追踪（通过Frame Pointer）
perf record -F 99 -p PID -g -- sleep 10
# 进行栈追踪（通过DWARF）
perf record -F 99 -p PID --call-graph dwarf sleep 10
# 全局性栈追踪
perf record -F 99 -ag -- sleep 10  # 4.11之前
perf record -F 99 -g -- sleep 10   # 4.11之后
# 追踪某个容器的栈
perf record -F 99 -e cpu-clock --cgroup=docker/1d567f4393190204...etc... -a -- sleep 10

# 每发生10000次L1缓存丢失，进行一次采样
perf record -e L1-dcache-load-misses -c 10000 -ag -- sleep 5
# 每发生以100次最后级别的CPU缓存丢失，进行一次采用
perf record -e LLC-load-misses -c 100 -ag -- sleep 5 

# 采样内核指令
perf record -e cycles:k -a -- sleep 5 
# 采用用户指令
perf record -e cycles:u -a -- sleep 5 
# 精确采样用户指令，基于PEBS
perf record -e cycles:up -a -- sleep 5

# 追踪新进程的创建
perf record -e sched:sched_process_exec -a

# 追踪上下文切换
perf record -e context-switches -a
perf record -e context-switches -c 1 -a
perf record -e context-switches -ag
# 追踪通过sched跟踪点的上下文切换
perf record -e sched:sched_switch -a

# 追踪CPU迁移
perf record -e migrations -a -- sleep 10

# 追踪所有connect调用（出站连接）
perf record -e syscalls:sys_enter_connect -ag
# 追踪所有accepts调用（入站连接）
perf record -e syscalls:sys_enter_accept* -ag

# 追踪所有块设备请求
perf record -e block:block_rq_insert -ag
# 追踪所有块设备发起和完成
perf record -e block:block_rq_issue -e block:block_rq_complete -a
# 追踪100KB（200扇区）以上的块操作完成
perf record -e block:block_rq_complete --filter 'nr_sector > 200'
# 追踪所有同步写操作的完成
perf record -e block:block_rq_complete --filter 'rwbs == "WS"'
# 追踪所有写操作的完成
perf record -e block:block_rq_complete --filter 'rwbs ~ "*W*"'

# 采样Minor faults（RSS尺寸增加）
perf record -e minor-faults -ag
perf record -e minor-faults -c 1 -ag
# 采样页面错误
perf record -e page-faults -ag

# 追踪所有Ext4调用，并把结果写入到非Ext4分区
perf record -e 'ext4:*' -o /tmp/perf.data -a 

# 追踪kswapd唤醒事件
perf record -e vmscan:mm_vmscan_wakeup_kswapd -ag

# 添加Node.js USDT 探针，要求Linux 4.10+
perf buildid-cache --add `which node`
# 跟踪Node.js http__server__request USDT事件
perf record -e sdt_node:http__server__request -a 

此命令用于分析perf record生成的perf.data文件。

perf report [-i <file> | --input=file]

默认情况下，样本根据函数（符号）分类，数量最多的样本位于最前面：

#  Overhead        Command  Shared Object                      Symbol
+  21.70%          swapper  [kernel.kallsyms]              [k] 0xffffffff8104f45a
+   8.89%  qemu-system-x86  [kernel.kallsyms]              [k] 0xffffffff810496f6
+   3.32%             Xorg  [kernel.kallsyms]              [k] 0xffffffff8172da33
+   2.96%       vmware-vmx  [kernel.kallsyms]              [k] 0xffffffff81121880
+   2.23%           chrome  chrome                         [.] 0x0000000004fdb6e6
+   2.17%             java  [kernel.kallsyms]              [k] 0xffffffff8109f02b
+   1.71%           chrome  [kernel.kallsyms]              [k] 0xffffffff8172d982
+   1.56%             Xorg  [nvidia]                       [k] _nv008054rm
+   1.55%             Xorg  [nvidia]                       [k] _nv014095rm

各列含义如下：

1. Overhead，在对应函数中采样到的样本计数
2.  Command，样本从什么应用程序中采集到
3. Shared Object，样本来自的ELF镜像。如果：
   1. 应用程序是动态链接的，这里可能显示共享库的名称
   2. 如果样本来自内核空间，则一律显示伪ELF镜像名“kernel.kallsyms”
4. 第4列是特权级别，点号表示用户级别，k、g、u、H分别表示内核级别、客户机内核级别、客户机用户级别、hypervisor
5. 最后一列是符号名称，如果缺乏调试信息，则显示为0x开头的函数内存地址

你可以指定多种分组规则，对样本数进行统计。

下面的例子根据共享对象分组：

perf report --sort=dso

+  48.05%  [kernel.kallsyms]                                                                                                                                                             
+   8.06%  libglib-2.0.so.0.4600.1                                                                                                                                                       
+   5.81%  libc-2.19.so                                                                                                                                                                  
+   4.93%  [nvidia]                                                                                                                                                                      
+   2.83%  libgobject-2.0.so.0.4600.1                                                                                                                                                    
+   2.39%  [kvm_intel]

下面的例子根据CPU序号分组：

perf report --sort=cpu

+  17.10%  0                                                                                                                                                                             
+  15.21%  2                                                                                                                                                                             
+  14.76%  4                                                                                                                                                                             
+  12.81%  6                                                                                                                                                                             
+  11.98%  3                                                                                                                                                                             
+  10.00%  5                                                                                                                                                                             
+   9.85%  1                                                                                                                                                                             
+   8.28%  7

perf不知道如何从压缩内核（vmlinuz）中抽取符号，如果你的内核保留了调试符号，则可以用-k来指出未压缩内核的位置：

perf report -k /tmp/vmlinux

如果在record时收集了调用链，则Overhead可以在Children、Self两个列中显示。Children显示子代函数的样本计数、Self显示函数自己的样本计数

# 报告perf.data
perf report

# 显示样本数量
perf report -n

# 树状结构显示，展开，可以追踪到高成本的执行路径
perf report --stdio
# 每行显示一个帧，扁平化显示，按成本降序排列
perf report --stdio -n -g folded

此命令用于源码级别的分析。

所有被采样到的函数都会被反汇编，每个指令占据采样的比例会被输出。

如果应用程序以-ggdb编译，annotate还能够生成源码级别信息：

------------------------------------------------
 Percent |   Source code & Disassembly of noploop
------------------------------------------------
         :
         :
         :
         :   Disassembly of section .text:
         :
         :   08048484 <main>:
         :   #include <string.h>
         :   #include <unistd.h>
         :   #include <sys/time.h>
         :
         :   int main(int argc, char **argv)
         :   {
    0.00 :    8048484:       55                      push   %ebp
    0.00 :    8048485:       89 e5                   mov    %esp,%ebp
[...]
    0.00 :    8048530:       eb 0b                   jmp    804853d <main+0xb9>
         :                           count++;
   14.22 :    8048532:       8b 44 24 2c             mov    0x2c(%esp),%eax
    0.00 :    8048536:       83 c0 01                add    $0x1,%eax
   14.78 :    8048539:       89 44 24 2c             mov    %eax,0x2c(%esp)
         :           memcpy(&tv_end, &tv_now, sizeof(tv_now));
         :           tv_end.tv_sec += strtol(argv[1], NULL, 10);
         :           while (tv_now.tv_sec < tv_end.tv_sec ||
         :                  tv_now.tv_usec < tv_end.tv_usec) {
         :                   count = 0;
         :                   while (count < 100000000UL)
   14.78 :    804853d:       8b 44 24 2c             mov    0x2c(%esp),%eax
   56.23 :    8048541:       3d ff e0 f5 05          cmp    $0x5f5e0ff,%eax
    0.00 :    8048546:       76 ea                   jbe    8048532 <main+0xae>
[...]

再次强调一下刹车现象，百分比信息可能不准确。

对于压缩内核，你可以指定非压缩版本内核的位置，以解析符号：

perf annotate -k /tmp/vmlinux -d symbol 

显示支持的事件列表。

# 显示所有事件
perf list

# 显示跟踪点sched下的事件
perf list 'sched:*'

用于定义新的追踪点，实现动态追踪。

perf probe [options] --add=PROBE [...]
perf probe [options] PROBE
perf probe [options] --del=[GROUP:]EVENT [...]
perf probe --list[=[GROUP:]EVENT]
perf probe [options] --line=LINE
perf probe [options] --vars=PROBEPOINT
perf probe [options] --funcs

# 为tcp_sendmsg函数添加进入追踪点，--add可以省略
perf probe --add tcp_sendmsg

# 移除tcp_sendmsg进入追踪点
perf probe -d tcp_sendmsg

# 为tcp_sendmsg函数添加退出追踪点
perf probe 'tcp_sendmsg%return'

# 显示tcp_sendmsg的可用变量，需要debuginfo
perf probe -V tcp_sendmsg
# 显示tcp_sendmsg的可用变量和外部变量
perf probe -V tcp_sendmsg --externs

# 显示tcp_sendmsg可用的行探针
perf probe -L tcp_sendmsg

# 显示tcp_sendmsg的81行可用的探针
perf probe -V tcp_sendmsg:81

# 为tcp_sendmsg添加进入进入追踪点，使用3个参数寄存器（依赖于平台）
perf probe 'tcp_sendmsg %ax %dx %cx'

# 为tcp_sendmsg添加进入进入追踪点，且将cx寄存器设置别名bytes（依赖于平台）
perf probe 'tcp_sendmsg bytes=%cx'

# 追踪tcp_sendmsg，要求%cx变量大于100
perf record -e probe:tcp_sendmsg --filter 'bytes > 100'

# 捕获返回值
perf probe 'tcp_sendmsg%return $retval'

# 为tcp_sendmsg和它的入口参数size添加追踪点，需要debuginfo，但是不依赖平台
perf probe 'tcp_sendmsg size'

# 为tcp_sendmsg和size、Socket状态添加追踪点
perf probe 'tcp_sendmsg size sk->__sk_common.skc_state'

# size大于0并且套接字状态不为TCP_ESTABLISHED时追踪tcp_sendmsg
perf record -e probe:tcp_sendmsg --filter 'size > 0 && skc_state != 1' -a

# 在tcp_sendmsg的81行添加追踪点，使用局部变量seglen
perf probe 'tcp_sendmsg:81 seglen'

# 为libc的用户态malloc函数添加探针
perf probe -x /lib64/libc.so.6 malloc

# 列出可用的动态探针
perf probe -l?

该命令使用额外的信息来增强事件流。

进行10秒钟的剖析：

perf record -a -g sleep 10

根据应用程序的名称进行分组，整体上根据样本的执行成本进行排序：

perf report --sort comm,dso

可以展开执行成本高的项，追踪到CPU时间都消耗在哪里了：

对于上面这个例子，可以看到，kubelet消耗的资源主要用于Prometheus相关的指标收集，以及grpc的客户端。

perf stat -- tar xzf ideaIU-2018.3.3.tar.gz 

 Performance counter stats for 'tar xzf ideaIU-2018.3.3.tar.gz':
    # 反映CPU利用率
       9725.627068 task-clock (msec)         #    0.941 CPUs utilized          
    # 上下文切换数量
            45,568 context-switches          #    0.005 M/sec                  
             1,370 cpu-migrations            #    0.141 K/sec        
    # 页面错误数量          
               623 page-faults               #    0.064 K/sec                  
    # 经过的时钟周期的数量
    36,249,427,884 cycles                    #    3.727 GHz                    
    # IPC，每时钟周期指令数（instructions per cycle），通常越高越好，表示工作处理过程是优化的
    # 但是，最好还是检查实际执行的指令，Spin loop就是高指令频率但是实际上什么事都不做的反例
    46,378,956,536 instructions              #    1.28  insns per cycle
     # 分支和分支预测失败
     8,274,686,762 branches                  #  850.813 M/sec                  
       214,332,307 branch-misses             #    2.59% of all branches        

      10.334029429 seconds time elapsed

perf_events支持使用固定频率来采样指令指针或栈追踪，进而分析CPU使用。采样频率通过-F选项指定。

频率可以选用99，而非100HZ，以避免采样和某些周期性活动的步调完全一致而导致结果失真。如果需要更高分辨率的采样，可以使用997这样的频率，但是注意频率越高剖析本身的成本也越高。

示例：

# 以99HZ频率，全局的采样30秒
perf record -F 99 -a -g -- sleep 30

除了定时触发（固定频率采样），采样也可以由特定的CPU硬件计数器触发。使用这些计数器可以分析缓存丢失、memory stall cycles（由于访问内存而导致的时钟周期浪费，内存访问速度相对CPU时钟周期要慢的多）等更低级别的处理器事件。

可用的事件列表：

perf list | grep Hardware
  cpu-cycles OR cycles                               [Hardware event]
  instructions                                       [Hardware event]
  cache-references                                   [Hardware event]
  cache-misses                                       [Hardware event]
  branch-instructions OR branches                    [Hardware event]
  branch-misses                                      [Hardware event]
  bus-cycles                                         [Hardware event]
  ref-cycles                                         [Hardware event]
  L1-dcache-loads                                    [Hardware cache event]
  L1-dcache-load-misses                              [Hardware cache event]
  L1-dcache-stores                                   [Hardware cache event]
  L1-dcache-store-misses                             [Hardware cache event]
  L1-dcache-prefetch-misses                          [Hardware cache event]
  L1-icache-load-misses                              [Hardware cache event]
  LLC-loads                                          [Hardware cache event]
  LLC-stores                                         [Hardware cache event]
  LLC-prefetches                                     [Hardware cache event]
  dTLB-loads                                         [Hardware cache event]
  dTLB-load-misses                                   [Hardware cache event]
  dTLB-stores                                        [Hardware cache event]
  dTLB-store-misses                                  [Hardware cache event]
  iTLB-loads                                         [Hardware cache event]
  iTLB-load-misses                                   [Hardware cache event]
  branch-loads                                       [Hardware cache event]
  branch-load-misses                                 [Hardware cache event]
  mem:<addr>[:access]                                [Hardware breakpoint]

如果每当发生这些事件，就记录栈追踪，对系统性能有严重的影响。因此，通常使用-c选项，当计数器增加一定数量后，记录一次栈追踪：

perf record -e L1-dcache-load-misses -c 10000 -ag -- sleep 5

上面这个例子，每当L1缓存丢失10000次，记录一次栈追踪。

下面的命令统计所有调用次数大于0的系统调用的数量：

perf stat -e 'syscalls:sys_enter_*' tar xzf ideaIU-2018.3.3.tar.gz 2>&1 | awk '$1 != 0'
 Performance counter stats for 'tar xzf ideaIU-2018.3.3.tar.gz':

                 2      syscalls:sys_enter_statfs                                   
            12,417      syscalls:sys_enter_utimensat                                   
  ...                                 
            12,417      syscalls:sys_enter_unlinkat                                   
  ...                                
            12,432      syscalls:sys_enter_newfstat                                   
                 1      syscalls:sys_enter_lseek                                    
           184,818      syscalls:sys_enter_read                                     
           192,154      syscalls:sys_enter_write                                    
                12      syscalls:sys_enter_access                                   
            12,417      syscalls:sys_enter_fchmod                                   
            12,417      syscalls:sys_enter_fchown                                   
                26      syscalls:sys_enter_open                                     
            24,834      syscalls:sys_enter_openat                                   
            12,442      syscalls:sys_enter_close                                                                 
  ...
      38.365080478 seconds time elapsed

可以看到，主要的系统调用都是read/write。

使用strace命令可以获得类似的结果，但是strace的成本要高的多。测试结果显示，perf可能让程序变慢2.5倍，而strace则会让程序变慢高达60倍。

perf record -e sched:sched_process_exec -a
# Ctrl-C
perf report -n --sort comm --stdio

# Overhead       Samples  Command
# ........  ............  .......
#
    32.14%             9  ionice 
    32.14%             9  nice   
    21.43%             6  du     
    10.71%             3  find   
     3.57%             1  ipset

追踪点sched:sched_process_exec在某个进程调用exec()产生另外一个进程时生效，这通常是新进程的产生方式。但是这个例子的结果不一定准确，原因是：

1. 进程可能fork()出子进程，追踪点sched:sched_process_fork可以用于这种情况
2. 应用程序可以reexec —— 针对自己再次调用exec() —— 这种用法可以清空地址空间，但是不会产生新进程

某些时候你希望了解服务器发起了哪些网络连接，是哪些进程发起的，为何发起。这些网络连接可能是延迟的根源。

追踪connect系统调用，即可了解出站连接：

perf record -e syscalls:sys_enter_connect -ag
perf report --stdio

# Children      Self  Trace output
# ........  ........  ............................................................
#
     5.88%     5.88%  fd: 0x00000005, uservaddr: 0xc4206fa390, addrlen: 0x0000001b
            |
            ---0x894812ebc0312874
               0xc42008e000
               runtime.main
               main.main
               github.com/projectcalico/node/pkg/readiness.Run
               github.com/projectcalico/node/pkg/readiness.checkBIRDReady
               github.com/projectcalico/node/pkg/readiness/bird.GRInProgress
               net.Dial
               net.(*Dialer).Dial
               net.(*Dialer).DialContext
               net.dialSerial
               net.dialSingle
               net.dialUnix
               net.unixSocket
               net.socket
               net.(*netFD).dial
               net.(*netFD).connect
               syscall.Connect
               syscall.Syscall

可以看到，占比最高的出站连接是由Calico Node容器发起的。

通过剖析套接字缓冲的使用情况，也是定位到什么代码使用了最多的网络I/O的一种方法：

perf record -e 'skb:consume_skb' -ag

使用perf可以了解应用程序为何休眠、在何处休眠、休眠多久。主要通过收集sched_stat、sched_switch事件实现。

剖析的目标代码如下：

for (i = 0; i <  10; i++) {
        ts1.tv_sec = 0;
        ts1.tv_nsec = 10000000;
        // 休眠
        nanosleep(&ts1, NULL);

        tv1.tv_sec = 0;
        tv1.tv_usec = 40000;
        // 休眠
        select(0, NULL, NULL, NULL,&tv1);
}

执行下面的命令开始剖析：

./perf record -e sched:sched_stat_sleep -e sched:sched_switch  -e sched:sched_process_exit -g -o perf.data.raw  sleep_test

合并sched_start、sched_switch事件：

perf inject -v -s -i perf.data.raw -o perf.data

报告：

perf report --stdio --show-total-period -i perf.data

  100.00%     502408738      foo  [kernel.kallsyms]  [k] __schedule
               |
               --- __schedule
                   schedule
                  |          
                  |--79.85%-- schedule_hrtimeout_range_clock
                  |          schedule_hrtimeout_range
                  |          poll_schedule_timeout
                  |          do_select
                  |          core_sys_select
                  |          sys_select
                  |          system_call_fastpath
                  |          __select
                  |          __libc_start_main
                  |          
                   --20.15%-- do_nanosleep
                             hrtimer_nanosleep
                             sys_nanosleep
                             system_call_fastpath
                             __GI___libc_nanosleep
                             __libc_start_main

The post 利用perf剖析Linux应用程序 appeared first on 绿色记忆.

这是一个网络协议，用于通过网络来同步系统时钟。

在Ubuntu下，你可以使用timedatectl、timedatectl（从16.04开始，用于代替ntpdate / ntp）执行时钟同步，或者安装chrony以成为NTP服务器。

timesyncd默认已经安装，用来代替ntpdate以及chrony的客户端部分。

要查看当前时间、时间配置，可以执行：

timedatectl status
      Local time: 四 2018-10-11 13:57:39 CST
  Universal time: 四 2018-10-11 05:57:39 UTC
        RTC time: 四 2018-10-11 05:57:39
       Time zone: Asia/Shanghai (CST, +0800)
# 启用时钟同步后，显示为yes
 Network time on: yes
# 如果和远程NTP服务器成功同步，显示为yes
NTP synchronized: yes
 RTC in local TZ: no

要启用时钟同步，执行：

timedatectl set-ntp true

显示可用的时区：

timedatectl list-timezones | grep Shanghai

修改时区：

timedatectl set-timezone Asia/Shanghai

这是负责执行时钟同步的后台服务：

systemctl status systemd-timesyncd.service

配置文件位置是 /etc/systemd/timesyncd.conf、/timesyncd.conf.d/

配置文件示例：

[Time]
NTP=0.cn.pool.ntp.org 1.cn.pool.ntp.org 2.cn.pool.ntp.org 3.cn.pool.ntp.org
FallbackNTP=ntp.ubuntu.com

systemctl status systemd-timesyncd.service 

# 同步失败
10月 11 13:49:56 Carbon systemd-timesyncd[730]: Timed out waiting for reply from 10.0.8.1:123 (ntp.gmem.cc). 

# 同步成功
10月 11 13:55:22 Carbon systemd-timesyncd[44163]: Synchronized to time server 10.0.8.1:123 (ntp.gmem.cc). 

要成为NTP服务器，可以安装chrony、ntpd，或者open-ntp。推荐chrony。

Chrony也可以作为NTP客户端，因为它可以从其它NTP服务器同步时间。

apt install -y chrony

上面的命令会安装两个程序：chronyd为NTP服务守护进程，chronyc为控制chronyd的命令行接口。

配置文件路径为 /etc/chrony/chrony.conf，示例：

# 上游服务器列表
#                        该参数表示在头四次 NTP 请求以 2s 或者更短的间隔，而不是以 minpoll x 
#                        指定的最小间隔，这样的设置可以让 chronyd 启动时快速进行一次同步
#                        其它参数   minpoll x = 6      maxpoll x = 9
server 0.cn.pool.ntp.org iburst
server 1.cn.pool.ntp.org iburst
server 2.cn.pool.ntp.org iburst
server 3.cn.pool.ntp.org iburst
# 要使用本地NTP服务器，可以将上面的删除，然后添加自己的：
server 10.0.0.1 iburst

# 作为服务器运行
# 允许哪些客户端访问当前NTP服务器
allow
allow 192.168.1.0/24

# 即使当前服务器无法联系到上游，也允许它对外提供时钟服务
local stratum 10


# 启用内核时间与 RTC 时间同步，自动写回硬件
rtcsync

配置完毕后，需要重启守护程序：

systemctl daemon-reload
systemctl restart chrony.service

# 查看 NTP 服务器的在线和离线状态
chronyc activity

# 查看 Chrony 服务的日志
journalctl -u chronyd

# 检查 NTP 访问是否对特定主机可用
chronyc accheck

# 该命令会显示有多少 NTP 源在线/离线
chronyc activity

# 手动添加一台新的 NTP 服务器
chronyc add server

# 在客户端报告已访问到服务器
chronyc clients

# 手动移除 NTP 服务器或对等服务器
chronyc delete

# 手动设置守护进程时间
chronyc settime

# 校准时间服务器，显示系统时间信息
chronyc tracking

# 检查 NTP 访问是否对特定主机可用
chronyc accheck

# 查看时间同步源
chronyc sources -v

# 查看时间同步源状态
chronyc sourcestats -v

The post Ubuntu的时钟同步 appeared first on 绿色记忆.

sysrqd是一个简单的守护程序，允许你透过网络发送SysRQ快捷键。某些情况下，远程机器网络可以连通，但是SSH无法登录，可以利用sysrqd强制重启。

apt install -y sysrqd
echo "password" > /etc/sysrqd.secret
service sysrqd restart

sysrqd默认监听4094端口，在客户机上，使用telnet登录：

telnet remote-ip 4094

根据提示输入密码。然后输入SysRQ快捷键即可。输入q可以退出telnet。

The post 使用sysrqd进行远程控制 appeared first on 绿色记忆.

pushd  /opt/gitea
mkdir -p custom/conf/
mkdir repos

wget -O gitea https://dl.gitea.io/gitea/1.3.2/gitea-1.3.2-linux-amd64
chmod +x gitea

nohup /opt/gitea/gitea web > /dev/null 2>&1 &

RUN_USER = root
RUN_MODE = prod
APP_NAME = Gmem Gitea

[repository]
ROOT = /opt/gitea/repos

[server]
PROTOCOL         = https
DOMAIN           = git.gmem.cc
HTTP_ADDR        = 0.0.0.0
HTTP_PORT        = 3443
; 证书需要完整的链
CERT_FILE        = /etc/letsencrypt/live/git.gmem.cc/fullchain.pem
KEY_FILE         = /etc/letsencrypt/live/git.gmem.cc/privkey.pem
SSH_DOMAIN       = git.gmem.cc
ROOT_URL         = https://git.gmem.cc/
DISABLE_SSH      = false
SSH_PORT         = 22
LFS_START_SERVER = true
LFS_CONTENT_PATH = /opt/gitea/data/lfs
LFS_JWT_SECRET   = s52JAPPWiOFpp8CZiPHrlGeHWtwv6WCphZtBG5vNLE8
OFFLINE_MODE     = false


[mailer]
ENABLED = false

[service]
REGISTER_EMAIL_CONFIRM            = false
ENABLE_NOTIFY_MAIL                = false
DISABLE_REGISTRATION              = true
ENABLE_CAPTCHA                    = false
REQUIRE_SIGNIN_VIEW               = false
DEFAULT_KEEP_EMAIL_PRIVATE        = false
DEFAULT_ALLOW_CREATE_ORGANIZATION = true
DEFAULT_ENABLE_TIMETRACKING       = true
NO_REPLY_ADDRESS                  = noreply@gmem.cc
[picture]
DISABLE_GRAVATAR        = false
ENABLE_FEDERATED_AVATAR = false

[openid]
ENABLE_OPENID_SIGNIN = true
ENABLE_OPENID_SIGNUP = false

[session]
PROVIDER = file

[log]
MODE      = file
LEVEL     = Info
ROOT_PATH = /opt/gitea/log

The post 使用Gitea搭建Git服务器 appeared first on 绿色记忆.

Ansible是一个自动化IT工具，能够配置系统、部署软件、编排复杂的IT任务（例如CD、零停机滚动更新）。

Ansible默认通过 SSH 协议管理，在管理机需要Python2.7环境，在托管机上需要Python 2环境。

# 下面的软件包在老版本Ubuntu上叫做python-software-properties
sudo apt-get install software-properties-common
sudo apt-add-repository ppa:ansible/ansible
sudo apt-get update
sudo apt-get install ansible

# 被管理的主机上需要安装Python2
sudo apt-get install python-minimal

/home/alex/Python/3.5.1/bin/pip install ansible 

Ansible支持从多个位置读取配置选项，包括环境变量、命令行参数、名为ansible.cfg的ini文件。

ini文件的搜索顺序为：

1. 环境变量ANSIBLE_CONFIG指定的位置
2. 当前目录的ansible.cfg
3. ~/.ansible.cfg
4. /etc/ansible/ansible.cfg

配置文件中以#或者;开头的行为注释。

[defaults]
; 主机清单文件位置
inventory      = /etc/ansible/hosts
; 远程SSH端口
remote_port    = 22
; SSH超时
timeout = 10
; 远程用户
remote_user = root
; SSH身份验证使用的私钥位置
private_key_file =/home/alex/Documents/puTTY/gmem.key
; 禁止由于不在known_hosts中导致的警告
; 等价于 export ANSIBLE_HOST_KEY_CHECKING=False
host_key_checking = False
; 和远程主机通信时，并行进程的数量
forks = 10
; 角色根目录
roles_path = /app/tops/roles
; 主机清单
inventory = /app/tops/host_vars/all.ini
; 控制Fact（远程系统变量）收集行为：
;   implicit  每次执行剧本，都收集
;   smart  避免不必要的收集，节约时间
gathering = smart
; Fact存储方式
fact_caching = jsonfile
; 连接到Fact存储的方式，对于jsonfile，需要指定一个目录
fact_caching_connection = ./.cache
; Fact缓存过期时间
fact_caching_timeout = 3600
; 剧本的标准输出回调，决定输出的显示方式
;   json
;   debug
;   skippy
stdout_callback = debug
; 额外启用的回调，从2.0开始Ansible的所有回调插件可用，但是默认是禁用状态。该设置让你可以指定哪些回调插件启用
;   timer 这个回调插件可以计算整个 playbook 的运行时间
;   mail 这个回调插件可以实现发送邮件的功能
;   profile_roles 这个插件是在执行中添加耗时
;
callback_whitelist = profile_tasks

全部可用配置项请参考：https://ansible-tran.readthedocs.io/en/latest/docs/intro_configuration.html

所谓主机清单（Host Inventory）是一个配置文件，来指定需要被管理的主机列表。主机清单的默认位置在/etc/ansible/hosts。

所有主机都属于

all

; 方括号内的是组名，每个主机都可以属于多个组
[k8s]
xenial-100.gmem.cc
xenial-101.gmem.cc
xenial-102.gmem.cc
xenial-103.gmem.cc
xenial-104.gmem.cc
xenial-105.gmem.cc

一个组，可以作为另外一个组的成员：

; 组1
[atlanta]
host1
host2

; 组2
[raleigh]
host2
host3

; 组的组    该关键字表示定义组的成员
[southeast:children]
atlanta
raleigh

; 父组的变量
[southeast:vars]
some_server=foo.southeast.example.com
halon_system_timeout=30
self_destruct_countdown=60
escape_pods=2 

[vms]
xenial-[100-200].gmem.cc
;    1:50等价
www[01:50].example.com 
db-[a:f].example.com

; 可以为主机设置别名，并指定主机变量
; 别名  ansible_开头的预定义变量
;                       SSH端口                SSH IP地址   通过SSH连接
jumper ansible_ssh_port=5555 ansible_ssh_host=192.168.1.50 ansible_connection=ssh

变量可以在Playbook（剧本）中引用。

除了主机变量，还可以定义属于整个组的变量：

[atlanta]
host1
host2

; 组名    这个关键字表示该段定义的是变量
[atlanta:vars]
ntp_server=ntp.atlanta.example.com
proxy=proxy.atlanta.example.com

在清单中定义所有变量不是最佳实践，你可以将它们放在独立的YAML中，这些YAML会和清单文件关联。

假设清单文件

/etc/ansible/hosts

/etc/ansible/group_vars/master     组变量
/etc/ansible/group_vars/worker     组变量
/etc/ansible/host_vars/xenial-100  主机变量

上述三个文件，还可以创建为目录，并在里面定义任意数量的文件，在这些文件里面定义变量。只需要改目录名和组/主机名一致即可：

/etc/ansible/group_vars/master/sysctl
/etc/ansible/group_vars/master/connection

Ansible 1.2+，group_vars、host_vars可以放在：

1. inventory文件所在目录
2. playbook文件所在目录

如果两个目录下都有，则playbook覆盖inventory。

建议将inventory和变量一起纳入版本控制管理。

使用ansible命令可以群发即席的命令给一群主机：

ansible <host-pattern> [options]

#       匹配目标主机的模式     执行的模块        传递给模块的参数   进一步限制主机范围
ansible <pattern_goes_here> -m <module_name> -a <arguments>  -l <group-or-@file>
# 示例
ansible webservers -m service -a "name=httpd state=restarted"  -l @hosts.txt


#       组   模块    登陆到机器的用户  改变身份                   询问密码
ansible all -m ping -u root        --sudo --sudo-user batman  --ask-sudo-pass

# 在所有主机上执行Shell命令
ansible all -u root -a "/bin/echo hello"

# 拷贝当前主机上的文件/etc/hosts到所有k8s组中的主机
ansible k8s -m copy -a "src=/etc/hosts dest=/tmp/hosts"

# 全部重启                            并发10个进程来执行
ansible -u root lb -a "/sbin/reboot" -f 10

# 额外的角色搜索路径
roles_path = /opt/mysite/roles:/opt/othersite/roles

为了避免重复输入命令，Ansibel提供了Playbook脚本功能，脚本文件的格式为YAML。调用脚本的语法如下：

#                剧本文件     并发度
ansible-playbook deploy.yml  -f 10

下面是一个脚本示例：

---
# 主机名、组名、或者all
- hosts: web
  # 定义变量
  vars:
    http_port: 80
    max_clients: 200
  # 远程登陆用户
  remote_user: root
  # 需要在远程主机上执行的任务列表，安装定义的顺序依次执行
  tasks:
  - name: ensure apache is at the latest version
    # 安装软件
    yum: pkg=httpd state=latest
    # 参数也可以作为子元素
    yum:
      pkg: httpd
      state: lastest
  
  - name: Write the configuration file
    # 写入配置文件
    template: src=templates/httpd.conf.j2 dest=/etc/httpd/conf/httpd.conf
    # 发布事件
    notify:
    - restart apache

  - name: ensure apache is running
    service: name=httpd state=started
  # 事件监听器
  handlers:
    - name: restart apache
      service: name=httpd state=restarted

# 可以针对另外一组主机声明脚本
- hosts: k8s

模块就是Ansible的命令。调用模块是可以指定不同的参数，就像调用Bash命令那样。

使用

-m

-a

#                   参数格式"name1=value1 name2=value2"
ansible all -m copy -a "src=/etc/hosts dest=/tmp/hosts"
ansible web -m yum -a "name=httpd state=present"

在Playbook脚本中每个任务（Task的子元素）都对应一个模块调用。

所有模块的文档参考：http://docs.ansible.com/ansible/modules_by_category.html

ansible -m debug -a "var=hostvars[inventory_hostname]"

---
- hosts: k8s
  tasks:
    - name: test
      debug:
        msg: "{{ inventory_hostname }} has gateway {{ ansible_default_ipv4.gateway }}"
        # 也可以打印变量
        var: hostvars[inventory_hostname]["ansible_default_ipv4"]["gateway"]

- copy:
    src: /srv/myfiles/foo.conf
    dest: /etc/foo.conf
    owner: foo
    group: foo
    mode: 0644
    # 备份被替换的文件
    backup: yes

- name: sync .helm directory
  synchronize:
    src:  /home/alex/.helm
    dest: /root/.helm

{{ }}

- template:
    src: etc/ssh/sshd_config.j2
    dest: /etc/ssh/sshd_config.j2
    owner: root
    group: root
    mode: '0600'
    # 校验拷贝的文件是否有效
    validate: /usr/sbin/sshd -t %s
    backup: yes

# 修改文件模式
- file:
    path: /etc/foo.conf
    owner: foo
    group: foo
    mode: 0644
    mode: "u=rw,g=r,o=r"
    mode: "u+rw,g-wx,o-rwx"

# 创建软链接
- file:
    src: /file/to/link/to
    dest: /path/to/symlink
    owner: foo
    group: foo
    state: link

# 创建新文件
- file:
    path: /etc/foo.conf
    state: touch
    mode: "u=rw,g=r,o=r"

# 创建目录
- file:
    path: /etc/some_directory
    state: directory
    mode: 0755

# 创建账户
- user:
    name: johnd
    comment: "John Doe"
    uid: 1040
    group: admin
# 删除账户
- user:
    name: johnd
    state: absent
    remove: yes

# 修改属性
- user:
    name: jsmith
    #创建SSH 私钥
    generate_ssh_key: yes
    ssh_key_bits: 2048
    ssh_key_file: .ssh/id_rsa

- user:
    name: james18
    shell: /bin/zsh
    groups: developers
    # 设置账户过期时间
    expires: 1422403387

- name: 安装最新版本的包，已经安装则替换老版本
    yum:
      name: httpd
      state: latest

- name: 安传个指定版本
    yum:
      name: httpd-2.2.29-1.4.amzn1
      state: present

- name: 删除软件包
    yum:
      name: httpd
      state: absent
- name: 从本地目录安装
  yum:
    name: /usr/local/src/nginx-release-centos-6-0.el6.ngx.noarch.rpm
    state: present 

- name: 更新仓库缓存并安装软件包foo
  apt:
    name: foo
    update_cache: yes

- name: 安装软件包但是不启动
  apt: name=apache2 state=present
  environment:
    RUNLEVLEL: 1
    http_proxy: http://10.0.0.1:8088
- name: 移除软件包
  apt: name=foo state=absent

- name: 安装指定版本的软件包
  apt:
    name: foo=1.00
    state: present

- name: 更新所有软件包到最新版本
  apt:
    upgrade: dist

- name: 仅仅执行apt-get update
  apt:
    update_cache: yes

- name: 安装Deb包
  apt:
    deb: /tmp/mypackage.deb

- name: 安装foo包的build依赖
  apt:
    pkg: foo
    state: build-dep

- name: 移除无用依赖包
  apt:
    autoremove: yes

- name: 安装多个软件包
  apt: name={{item}} state=installed
  with_items:
    - kubelet
    - kubectl

# 确保软件包安装
- name: Install ntpdate
  package:
    name: ntpdate
    state: present

# 确保软件包移除
- name: Remove the apache package
  package:
    name: "{{ apache }}"
    state: absent

# 确保软件包是最新版本
- name: Install the latest version of Apache and MariaDB
  package:
    name:
      - httpd
      - mariadb-server
    state: latest 

- name: 从Key服务器添加一个Key
  apt_key:
    keyserver: keyserver.ubuntu.com
    id: 36A1D7869245C8950F966E92D8576A8BA88D21E9

- name: 从URL添加Key
  apt_key:
    url: https://ftp-master.debian.org/keys/archive-key-6.0.asc
    state: present

- name: Add an Apt signing key, will not download if present

# 添加指定的仓库到系统源列表
- apt_repository:
    repo: deb http://archive.canonical.com/ubuntu hardy partner
    state: present

# 添加指定的仓库到系统源列表，存放在指定的文件中
- apt_repository:
    repo: deb http://dl.google.com/linux/chrome/deb/ stable main
    state: present
    filename: google-chrome

# 移除指定的仓库
- apt_repository:
    repo: deb http://archive.canonical.com/ubuntu hardy partner
    state: absent

# 从PPA安装仓库
- apt_repository:
    repo: ppa:nginx/stable

# 开服务
- service:
    name: httpd
    state: started
# 关服务
- service:
    name: httpd
    state: stopped
# 重起服务
- service:
    name: httpd
    state: restarted
# 重载服务
- service:
    name: httpd
    state: reloaded
# 设置开机启动
- service:
    name: httpd
    enabled: yes

- name: test $home
  shell: echo "Test" > ~/tmp/test


# 多行命令
- hosts: k8s
  tasks:
    - name: Pull images
      shell: |
        docker pull $IMAGE_REPO/kube-apiserver-amd64:v1.10.2
        docker pull $IMAGE_REPO/kube-scheduler-amd64:v1.10.2
      args:
        # 指定工作目录
        chdir: somedir/
        # 指定使用的脚本解析器
        executable: /bin/bash

ansible webservers -m git \
  -a "repo=git://foo.example.org/repo.git dest=/srv/myapp version=HEAD"

- name: "设置多个变量，用空格分隔"
  set_fact: one_fact="something" other_fact="{{ local_var }}"

- name: "另外一种多变量设置风格"
  set_fact:
    one_fact: something
    other_fact: "{{ local_var * 2 }}"
    another_fact: "{{ some_registered_var.results | map(attribute='ansible_facts.some_fact') | list }}"

- name: "允许缓存变量"
  set_fact:
    one_fact: something
    other_fact: "{{ local_var * 2 }}"
    cacheable: yes 

# 确保服务启动
- name: Make sure a service is running
  systemd:
    state: started
    name: httpd

# 确保服务停止
- name: Stop service cron on debian, if running
  systemd:
    name: cron
    state: stopped

# 发起daemon-reload并重启服务
- name: Restart service cron on centos, in all cases, also issue daemon-reload to pick up config changes
  systemd:
    state: restarted
    daemon_reload: yes
    name: crond

# 重新载入服务
- name: Reload service httpd, in all cases
  systemd:
    name: httpd
    state: reloaded

# 启用服务
- name: Enable service httpd and ensure it is not masked
  systemd:
    name: httpd
    enabled: yes
    # 被mask的Systemd单元无法启动
    masked: no

# 重新载入配置
- name: Just force systemd to reread configs (2.4 and above)
  systemd:
    daemon_reload: yes

- name: ensure kernel modules
  modprobe:
    name: "{{ item }}"
    # absent 表示卸载
    state: present
  with_items:
    - "br_netfilter"

剧本比即席任务复杂而强大的多，它可以：

1. 编排有序的执行过程，在多组机器间，来回有序的执行特别指定的步骤
2. 可以同步或异步的发起任务

Playbook的格式是YAML，它由一个或多个plays组成，它的内容是一个以plays为元素的列表。

在每个Play中，一组机器被映射为定义好的角色。

Play中包含Tasks，每个Task典型情况下是对某个Ansible模块的调用。

下面是一个简单的例子：

# 只有一个Play，它包含目标、变量、任务列表信息
---
  # 针对的主机，可以是主机、组的Pattern。所有任务都针对相同的主机
- hosts: webservers
  # 可以定义变量
  vars:
    http_port: 80
    max_clients: 200
  # 变量可以放在外部文件中，例如敏感信息
  vars_files:
  - /vars/external_vars.yml
  # 以什么用户登陆执行
  remote_user: root
  # 支持sudo
  sudo: yes
  sudo_user: postgres
  # 任务列表，注意任务是串行执行的，只有前一个执行完毕（不管有多少主机），后一个才开始执行
  tasks:
    # 每个任务都具有名称
  - name: ensure apache is at the latest version
    yum: pkg=httpd state=latest
    # 每个Task都可以覆盖用户
    remote_user: yourname
  - name: write the apache config file
    # 老版本中，需要写作 action: template，限制直接写模块名即可
    template: src=/srv/httpd.j2 dest=/etc/httpd.conf
    # 如果发生了变动（对于这个模块来说，就是目标文件内容发生了变化）
    # 则执行
    notify:
    # 需要注意，如果有多个Task都通知需要执行此Handler，只会执行一次
    - restart apache
  - name: ensure apache is running
    service: name=httpd state=started
  - name: run this command and ignore the result
    # 对于shell或command，如果不关心退出码，可以
    shell: /usr/bin/somecommand || /bin/true
    # 或者
    ignore_errors: True
  - name: Copy ansible inventory file to client
    # 参数太长，可以换行编写
    copy: src=/etc/ansible/hosts dest=/etc/ansible/hosts
            owner=root group=root mode=0644
    #                                    引用变量
  - name: create a virtual host file for {{ vhost }}
    template: src=somefile.j2 dest=/etc/httpd/conf.d/{{ vhost }}

  # 供引用的、发生变动后执行的处理器。通常都用来重启服务
  handlers:
    - name: restart apache
      service: name=httpd state=restarted

需要注意：

1. 如果一个 host 执行 task 失败，这个 host 将会从整个 playbook 的 rotation 中移除
2. 每个 task 的目标在于执行一个 moudle, 通常是带有特定的参数来执行.在参数中可以使用{{变量}}
3. 模块具有幂等性，多次执行，它只会做必要的动作，此外当远端系统被人改动时,可以重放 playbooks 达到恢复的目的。对于command、shell这样的模块，多次执行相当于反复调用命令，是否幂等取决于底层命令

注意：很多字段Role也可以用。

剧本、角色中都可以定义Task。Task具有以下通用字段：

delegate_to: localhost

对于任何一个主机，一个特定的Handler只会执行一次，不管它被Notify了多少次

Handlers 会在 'pre_tasks', 'roles', 'tasks', 和 'post_tasks' 之间自动执行，你也可以手工立即调用Handler：

tasks:
   - shell: some tasks go here
   # 立即调用
   - meta: flush_handlers
   - shell: some other tasks

编写一个巨大的Playbook文件，不利于维护。 可以将具有重用价值的部分独立编写，然后通过include引用。

include主要用于包含来自其它文件的Task，也可以包含来自其它文件的Play。Handlers本质上也是Task，亦可被引用。

用于被引用的Task列表，形式如下：

---
- name: placeholder foo
  command: /bin/foo

- name: placeholder bar
  command: /bin/bar

在Playbook中，include上述列表的语法：

tasks:
  - include: tasks/foo.yml

include还支持多种写法： 

# 1.0引入的语法
tasks:
  - include: wordpress.yml
    vars:
        wp_user: timmy
        some_list_variable:
          - alpha
          - beta
          - gamma

# 1.4之后，可以使用下面的语法

tasks:
  - { include: wordpress.yml, wp_user: timmy, ssh_keys: [ 'keys/one.txt', 'keys/two.txt' ] }

include的时候，可以传递变量，所谓参数化include：

# 
tasks: 
                           # 变量列表，在被包含文件中引用变量  {{ wp_user }}  
  - include: wordpress.yml wp_user=timmy
  - include: wordpress.yml wp_user=alice
  - include: wordpress.yml wp_user=bob

除了显式传递的变量之外，在Play的vars段中声明的变量，均可在被包含的列表中引用。

include也可以出现在handlers段： 

handlers:
  - include: handlers/handlers.yml

甚至，include还可以将Playbook包含到另外一个Playbook中，这种情况下，不支持传递变量：

# Play
- name: this is a play at the top level of a file
  hosts: all
  remote_user: root

  tasks:

  - name: say hi
    tags: foo
    shell: echo "hi..."

# 来自其它文件的Plays
- include: load_balancers.yml
- include: webservers.yml
- include: dbservers.yml

使用Role，使组织Playbook的最佳方式。Roles 基于特定的文件结构，去自动的加载某些 vars_files，tasks 以及 handlers。基于 roles 对内容进行分组，使得我们可以容易地与其他用户分享 roles

考虑下面的Ansible项目结构：

# 剧本
site.yml
webservers.yml
fooservers.yml
# 角色，可以被剧本引用
roles/
   common/
     # 部分目录可以不存在
     files/
     templates/
     tasks/
     handlers/
     vars/
     defaults/
     meta/
   webservers/
     files/          # copy、script模块引用的文件
     templates/      # template模块引用的模版
     tasks/          # main.yaml为该角色的主任务列表，main.yaml可以include该目录的其它文件中定义的任务
     handlers/       # main.yaml为该角色的Handler列表
     vars/           # 自动添加到引用该角色的Play中
     defaults/       # 为角色、该角色依赖的其它角色，定义默认变量
     meta/           # 依赖的其它角色

其中剧本webservers.yml的内容： 

---
- hosts: webservers
  # Play包含了两个角色
  roles:
     - common
     - webservers

对于该剧本包含的任何Role x：

1. 如果 roles/x/tasks/main.yml 存在, 其中列出的 tasks 将被添加到 play 中
2. 所有 include tasks 可以引用 roles/x/tasks/ 中的文件，不需要指明文件的路径
3. 如果 roles/x/handlers/main.yml 存在, 其中列出的 handlers 将被添加到 play 中
4. 如果 roles/x/vars/main.yml 存在, 其中列出的 variables 将被添加到 play 中
5. 如果 roles/x/meta/main.yml 存在, 其中列出的 “角色依赖” 将被添加到 roles 列表中，需要1.3+
6. 所有 copy tasks 可以引用 roles/x/files/ 中的文件，不需要指明文件的路径
7. 所有 script tasks 可以引用 roles/x/files/ 中的脚本，不需要指明文件的路径
8. 所有 template tasks 可以引用 roles/x/templates/ 中的文件，不需要指明文件的路径

包含角色时，可以指定参数：

- hosts: webservers
  roles:
    - common
    - { role: foo_app_instance, dir: '/opt/a',  port: 5000 }
    - { role: foo_app_instance, dir: '/opt/b',  port: 5001 }

---

- hosts: webservers
  roles:
    - { role: some_role, when: "ansible_os_family == 'RedHat'" }

对于Role 的每个Task，都会执行when中的判断，仅当结果为true，该Task才被包含到剧本中。

---

- hosts: webservers
  roles:
    - { role: foo, tags: ["bar", "baz"] }

Tags 是一种实现部分运行 playbook 的机制

如果你想在Role执行之前、之后，执行一些Task，使用下面的配置：

---

- hosts: webservers

  pre_tasks:
    - shell: echo 'hello'

  roles:
    - { role: some_role }

  tasks:
    - shell: echo 'still busy'

  post_tasks:
    - shell: echo 'goodbye'

注意，使用了Role的Play，如果同时还定义了tasks段，则其中的任务都在Role中的Task结束后才执行。 

你可以为角色、以及这些角色依赖（dependent，包含的其它，定义在角色的meta/main.yaml）的角色，设置默认变量。

这些变量在所有可用变量中拥有最低优先级，可能被其他地方定义的变量(包括 inventory 中的变量)所覆盖。

可以将其它角色，自动拉取到当前角色中。依赖的角色定义在 meta/main.yaml 中：

---
dependencies:
  #                   可以传递参数
  - { role: postgres, dbname: blarg, other_parameter: 12 }
  # 可以使用绝对路径引用Role
  - { role: '/path/to/common/roles/foo', x: 1 }
  # 甚至引用Git服务器、压缩包中的角色，可以指定友好角色名
  - { role: 'git+http://git.example.com/repos/role-foo,v1.1,foo' }
  - { role: '/path/to/tar/file.tgz,,friendly-name' }

我们知道，Role定义了完整的可执行实体，Playbook可以仅简单的引用、传递参数给它。

当Role依赖于其它Role时，被依赖的Role先执行，这个过程可以是递归的。 

默认情况下，被依赖的Role仅仅会执行一次。如果有两个Role同时依赖它，第二个依赖被忽略。要改变此行为，可以修改依赖规则：

---
allow_duplicates: yes
dependencies:
- { role: tire }
- { role: brake }


# 在上述配置下
---
dependencies:
- { role: wheel, n: 1 }
- { role: wheel, n: 2 }
- { role: wheel, n: 3 }
- { role: wheel, n: 4 }
# 多次依赖
---
allow_duplicates: yes
dependencies:
- { role: tire }
- { role: brake }
# 执行序列：
# tire(n=1)
# brake(n=1)
# wheel(n=1)
# tire(n=2)
# brake(n=2)
# wheel(n=2)
# ...
#

如果你自己开发了一个Ansible 模块，你甚至可以将它作为角色的一部分，进行分发。 

roles/
   my_custom_modules/
       library/
          module1
          module2

- hosts: webservers
  roles:
    - my_custom_modules
    - some_other_role_using_my_custom_modules
    - yet_another_role_using_my_custom_modules

这些自定义模块，在当前Role，以及后面执行的Role中可用。

你可以为主机或分组定义变量，具体参考前面的章节。

在Play中，你可以直接定义变量：

- hosts: webservers
  vars:
    http_port: 80

角色有vars、defaults目录，存放变量信息。

为了使用变量，你需要在Playbook以及它引用的文件中，使用Jinja模板。该模板语言使用

{{}}

template: src=foo.cfg.j2 dest={{ remote_install_path }}/foo.cfg

和Go Template是相似的。

需要注意，YAML语法要求，如果值以{{  }}开头的话我们需要将整行用双引号包起来，防止错误的解释为YAML字典：

# 错误
- hosts: app_servers
  vars:
      app_path: {{ base_path }}/22

# 正确
- hosts: app_servers
  vars:
       app_path: "{{ base_path }}/22 

类似于Go Template的函数语法：

{{ my_variable|default('my_variable is not defined') }}

Jinja2包含许多内置过滤器：https://jinja.palletsprojects.com/en/2.11.x/templates/#builtin-filters

Ansible模块通常会返回一个数据结构，你可以把模块调用的结果存放到一个变量中：

- hosts: web_servers

  tasks:

     - shell: /usr/bin/foo
       # 注册结果为变量
       register: foo_result
       ignore_errors: True

     - shell: /usr/bin/bar
       # 使用变量进行判断
       when: foo_result.rc == 5

这个数据结构包含的字段如下：

# 方括号语法
{{ ansible_eth0["ipv4"]["address"] }}
# 点好导航语法
{{ ansible_eth0.ipv4.address }}

Ansible会自动提供给你一些变量，即使你并没有定义过它们，这些变量名是预留的，用户不应当覆盖它们：

1. hostvars：可以让你访问其它主机的变量、包括哪些主机中获取到的facts
2. group_names：当前主机所在所有群组的列表
3. groups：inventory中所有群组/主机的列表。可以用来列举主机：
   

   {% for host in groups['app_servers'] %}
      {{ hostvars[host]['ansible_eth0']['ipv4']['address'] }}
   {% endfor %}

所有魔法变量的列表，请参考上文。

可以在调用Ansible命令时传递变量：

# ---

# - hosts: '{{ hosts }}'
#   remote_user: '{{ user }}'

#   tasks:
#      - ...

ansible-playbook release.yml --extra-vars "hosts=vipers user=starbuck"
                             # 支持JSON
                             --extra-vars '{"pacman":"mrs","ghosts":["inky","pinky","clyde","sue"]}'

从高到低：

命令行-e ⇨

Inventory中定义的连接变量（例如ansible_ssh_user）⇨

Play中的变量、included的变量、Role中的变量⇨

Inventory中的其它变量 ⇨

Facts ⇨

Role默认变量 

这是一类变量，但是它们的值是Ansible自动检测出来的，而非你去指定的。

使用命令

ansible hostname -m setup

"ansible_all_ipv4_addresses": [
    "REDACTED IP ADDRESS"
],
"ansible_all_ipv6_addresses": [
    "REDACTED IPV6 ADDRESS"
],
"ansible_architecture": "x86_64",
"ansible_bios_date": "09/20/2012",
"ansible_bios_version": "6.00",
"ansible_cmdline": {
    "BOOT_IMAGE": "/boot/vmlinuz-3.5.0-23-generic",
    "quiet": true,
    "ro": true,
    "root": "UUID=4195bff4-e157-4e41-8701-e93f0aec9e22",
    "splash": true
},
"ansible_date_time": {
    "date": "2013-10-02",
    "day": "02",
    "epoch": "1380756810",
    "hour": "19",
    "iso8601": "2013-10-02T23:33:30Z",
    "iso8601_micro": "2013-10-02T23:33:30.036070Z",
    "minute": "33",
    "month": "10",
    "second": "30",
    "time": "19:33:30",
    "tz": "EDT",
    "year": "2013"
},
"ansible_default_ipv4": {
    "address": "REDACTED",
    "alias": "eth0",
    "gateway": "REDACTED",
    "interface": "eth0",
    "macaddress": "REDACTED",
    "mtu": 1500,
    "netmask": "255.255.255.0",
    "network": "REDACTED",
    "type": "ether"
},
"ansible_default_ipv6": {},
"ansible_devices": {
    "fd0": {
        "holders": [],
        "host": "",
        "model": null,
        "partitions": {},
        "removable": "1",
        "rotational": "1",
        "scheduler_mode": "deadline",
        "sectors": "0",
        "sectorsize": "512",
        "size": "0.00 Bytes",
        "support_discard": "0",
        "vendor": null
    },
    "sda": {
        "holders": [],
        "host": "SCSI storage controller: LSI Logic / Symbios Logic 53c1030 PCI-X Fusion-MPT Dual Ultra320 SCSI (rev 01)",
        "model": "VMware Virtual S",
        "partitions": {
            "sda1": {
                "sectors": "39843840",
                "sectorsize": 512,
                "size": "19.00 GB",
                "start": "2048"
            },
            "sda2": {
                "sectors": "2",
                "sectorsize": 512,
                "size": "1.00 KB",
                "start": "39847934"
            },
            "sda5": {
                "sectors": "2093056",
                "sectorsize": 512,
                "size": "1022.00 MB",
                "start": "39847936"
            }
        },
        "removable": "0",
        "rotational": "1",
        "scheduler_mode": "deadline",
        "sectors": "41943040",
        "sectorsize": "512",
        "size": "20.00 GB",
        "support_discard": "0",
        "vendor": "VMware,"
    },
    "sr0": {
        "holders": [],
        "host": "IDE interface: Intel Corporation 82371AB/EB/MB PIIX4 IDE (rev 01)",
        "model": "VMware IDE CDR10",
        "partitions": {},
        "removable": "1",
        "rotational": "1",
        "scheduler_mode": "deadline",
        "sectors": "2097151",
        "sectorsize": "512",
        "size": "1024.00 MB",
        "support_discard": "0",
        "vendor": "NECVMWar"
    }
},
"ansible_distribution": "Ubuntu",
"ansible_distribution_release": "precise",
"ansible_distribution_version": "12.04",
"ansible_domain": "",
"ansible_env": {
    "COLORTERM": "gnome-terminal",
    "DISPLAY": ":0",
    "HOME": "/home/mdehaan",
    "LANG": "C",
    "LESSCLOSE": "/usr/bin/lesspipe %s %s",
    "LESSOPEN": "| /usr/bin/lesspipe %s",
    "LOGNAME": "root",
    "LS_COLORS": "rs=0:di=01;34:ln=01;36:mh=00:pi=40;33:so=01;35:do=01;35:bd=40;33;01:cd=40;33;01:or=40;31;01:su=37;41:sg=30;43:ca=30;41:tw=30;42:ow=34;42:st=37;44:ex=01;32:*.tar=01;31:*.tgz=01;31:*.arj=01;31:*.taz=01;31:*.lzh=01;31:*.lzma=01;31:*.tlz=01;31:*.txz=01;31:*.zip=01;31:*.z=01;31:*.Z=01;31:*.dz=01;31:*.gz=01;31:*.lz=01;31:*.xz=01;31:*.bz2=01;31:*.bz=01;31:*.tbz=01;31:*.tbz2=01;31:*.tz=01;31:*.deb=01;31:*.rpm=01;31:*.jar=01;31:*.war=01;31:*.ear=01;31:*.sar=01;31:*.rar=01;31:*.ace=01;31:*.zoo=01;31:*.cpio=01;31:*.7z=01;31:*.rz=01;31:*.jpg=01;35:*.jpeg=01;35:*.gif=01;35:*.bmp=01;35:*.pbm=01;35:*.pgm=01;35:*.ppm=01;35:*.tga=01;35:*.xbm=01;35:*.xpm=01;35:*.tif=01;35:*.tiff=01;35:*.png=01;35:*.svg=01;35:*.svgz=01;35:*.mng=01;35:*.pcx=01;35:*.mov=01;35:*.mpg=01;35:*.mpeg=01;35:*.m2v=01;35:*.mkv=01;35:*.webm=01;35:*.ogm=01;35:*.mp4=01;35:*.m4v=01;35:*.mp4v=01;35:*.vob=01;35:*.qt=01;35:*.nuv=01;35:*.wmv=01;35:*.asf=01;35:*.rm=01;35:*.rmvb=01;35:*.flc=01;35:*.avi=01;35:*.fli=01;35:*.flv=01;35:*.gl=01;35:*.dl=01;35:*.xcf=01;35:*.xwd=01;35:*.yuv=01;35:*.cgm=01;35:*.emf=01;35:*.axv=01;35:*.anx=01;35:*.ogv=01;35:*.ogx=01;35:*.aac=00;36:*.au=00;36:*.flac=00;36:*.mid=00;36:*.midi=00;36:*.mka=00;36:*.mp3=00;36:*.mpc=00;36:*.ogg=00;36:*.ra=00;36:*.wav=00;36:*.axa=00;36:*.oga=00;36:*.spx=00;36:*.xspf=00;36:",
    "MAIL": "/var/mail/root",
    "OLDPWD": "/root/ansible/docsite",
    "PATH": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
    "PWD": "/root/ansible",
    "SHELL": "/bin/bash",
    "SHLVL": "1",
    "SUDO_COMMAND": "/bin/bash",
    "SUDO_GID": "1000",
    "SUDO_UID": "1000",
    "SUDO_USER": "mdehaan",
    "TERM": "xterm",
    "USER": "root",
    "USERNAME": "root",
    "XAUTHORITY": "/home/mdehaan/.Xauthority",
    "_": "/usr/local/bin/ansible"
},
"ansible_eth0": {
    "active": true,
    "device": "eth0",
    "ipv4": {
        "address": "REDACTED",
        "netmask": "255.255.255.0",
        "network": "REDACTED"
    },
    "ipv6": [
        {
            "address": "REDACTED",
            "prefix": "64",
            "scope": "link"
        }
    ],
    "macaddress": "REDACTED",
    "module": "e1000",
    "mtu": 1500,
    "type": "ether"
},
"ansible_form_factor": "Other",
"ansible_fqdn": "ubuntu2.example.com",
"ansible_hostname": "ubuntu2",
"ansible_interfaces": [
    "lo",
    "eth0"
],
"ansible_kernel": "3.5.0-23-generic",
"ansible_lo": {
    "active": true,
    "device": "lo",
    "ipv4": {
        "address": "127.0.0.1",
        "netmask": "255.0.0.0",
        "network": "127.0.0.0"
    },
    "ipv6": [
        {
            "address": "::1",
            "prefix": "128",
            "scope": "host"
        }
    ],
    "mtu": 16436,
    "type": "loopback"
},
"ansible_lsb": {
    "codename": "precise",
    "description": "Ubuntu 12.04.2 LTS",
    "id": "Ubuntu",
    "major_release": "12",
    "release": "12.04"
},
"ansible_machine": "x86_64",
"ansible_memfree_mb": 74,
"ansible_memtotal_mb": 991,
"ansible_mounts": [
    {
        "device": "/dev/sda1",
        "fstype": "ext4",
        "mount": "/",
        "options": "rw,errors=remount-ro",
        "size_available": 15032406016,
        "size_total": 20079898624
    }
],
"ansible_nodename": "ubuntu2.example.com",
"ansible_os_family": "Debian",
"ansible_pkg_mgr": "apt",
"ansible_processor": [
    "Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz"
],
"ansible_processor_cores": 1,
"ansible_processor_count": 1,
"ansible_processor_threads_per_core": 1,
"ansible_processor_vcpus": 1,
"ansible_product_name": "VMware Virtual Platform",
"ansible_product_serial": "REDACTED",
"ansible_product_uuid": "REDACTED",
"ansible_product_version": "None",
"ansible_python_version": "2.7.3",
"ansible_selinux": false,
"ansible_ssh_host_key_dsa_public": "REDACTED KEY VALUE"
"ansible_ssh_host_key_ecdsa_public": "REDACTED KEY VALUE"
"ansible_ssh_host_key_rsa_public": "REDACTED KEY VALUE"
"ansible_swapfree_mb": 665,
"ansible_swaptotal_mb": 1021,
"ansible_system": "Linux",
"ansible_system_vendor": "VMware, Inc.",
"ansible_user_id": "root",
"ansible_userspace_architecture": "x86_64",
"ansible_userspace_bits": "64",
"ansible_virtualization_role": "guest",
"ansible_virtualization_type": "VMware"

Facts可以直接在Playbook中引用，例如获取第一块磁盘的型号：

{{ ansible_devices.sda.model }}

你可以为Play禁用Fact收集：

- hosts: whatever
  gather_facts: no

一般情况下，Facts都是Ansible自动检测的，目标主机的信息。

你可以在目标主机下放置配置文件，硬编码一些变量值：

[general]
asdf=1
bar=2

这将产生如下变量： 

# ansible <hostname> -m setup -a "filter=ansible_local"

"ansible_local": {
        "preferences": {
            "general": {
                "asdf" : "1",
                "bar"  : "2"
            }
        }
 }

可以在剧本或模板中引用这种变量：

{{ ansible_local.preferences.general.asdf }}

在一个主机上运行的剧本中，引用另外一个主机中的变量，是可能的：

{{ hostvars['asdf.example.com']['ansible_os_family'] }}

如果没有Facts缓存，则Ansible需要在当前主机和另外一台主机进行通信，获取必要的变量。这在大规模集群中，可能造成负担。

Facts缓存是一种分布式缓存，可以依托Jsonfile或Redis实现，解决上述问题。

可以使用逻辑表达式、Jinja2过滤器，来编写when，在运行时决定Task是否执行：

tasks:
  - name: "shutdown Debian flavored systems"
    command: /sbin/shutdown -t now
    when: ansible_os_family == "Debian"   
    # 使用过滤器
    when: result|success                
    when: ansible_os_family == "RedHat" and ansible_lsb.major_release|int >= 6
    # 取反
    when: not var0
    # 是否定义
    when: bar is not defined
    # 字符串包含
    when: "'reticulating splines' in output"
tasks:
    - command: echo {{ item }}
      # 在循环中使用
      with_items: [ 0, 2, 4, 6, 8, 10 ]
      when: item > 5

除了Task，你还可以在roles、include语句中使用when：

- include: tasks/sometasks.yml
  when: "'reticulating splines' in output"


- hosts: webservers
  roles:
     - { role: debian_stock_config, when: ansible_os_family == 'Debian' }

如果想在一个任务中干很多事，比如创建一群用户、安装很多包、或者重复一个轮询步骤直到收到某个特定结果，考虑使用循环支持。

循环变量是简单值：

- name: add several users
  # 通过item引用当前循环变量
  user: name={{ item }} state=present groups=wheel
  # 循环
  with_items:
     - testuser1
     - testuser2
  # 可以引用变量定义的列表
  with_items: "{{somelist}}"

循环变量是字典：

- name: add several users
  user: name={{ item.name }} state=present groups={{ item.groups }}
  with_items:
    - { name: 'testuser1', groups: 'wheel' }
    - { name: 'testuser2', groups: 'root' }

循环变量是哈希表的条目：

---
users:
  alice:
    name: Alice Appleworth
    telephone: 123-456-7890
  bob:
    name: Bob Bananarama
    telephone: 987-654-3210



tasks:
  - name: Print phone records
    #                   访问键             访问值
    debug: msg="User {{ item.key }} is {{ item.value.name }} ({{ item.value.telephone }})"
    with_dict: "{{users}}"

- name: give users access to multiple databases
  mysql_user: name={{ item[0] }} priv={{ item[1] }}.*:ALL append_privs=yes password=foo
  with_nested:
    # 外层变量
    - [ 'alice', 'bob' ]
    # 内层变量
    - [ 'clientdb', 'employeedb', 'providerdb' ]

对于变量定义：

---
users:
  - name: alice
    authorized:
      - /tmp/alice/onekey.pub
      - /tmp/alice/twokey.pub
    mysql:
        password: mysql-password
        hosts:
          - "%"
          - "127.0.0.1"
          - "::1"
          - "localhost"
        privs:
          - "*.*:SELECT"
          - "DB1.*:ALL"
  - name: bob
    authorized:
      - /tmp/bob/id_rsa.pub
    mysql:
        password: other-mysql-password
        hosts:
          - "db1"
        privs:
          - "*.*:SELECT"
          - "DB2.*:ALL"

如果我们想给每个name创建系统用户，并且为每个用户的每个authorized创建密钥登陆，可以：

- user: name={{ item.name }} state=present generate_ssh_key=yes
  # 遍历每个用户，创建用户
  with_items: "{{users}}"

#                          items.0表示当前外层变量   
#                                     items.1表示当前内层变量                          
- authorized_key: "user={{ item.0.name }} key='{{ lookup('file', item.1) }}'"
  with_subelements:
     # 外层是用户
     - users
     # 内层是当前用户的authorized列表（users[x].authorized）
     - authorized

类似的，创建MySQL用户

- name: Setup MySQL users
  mysql_user: name={{ item.0.user }} password={{ item.0.mysql.password }} 
              host={{ item.1 }} priv={{ item.0.mysql.privs | join('/') }}
  with_subelements:
    - users
    - mysql.hosts

---
- hosts: all

  tasks:

    # 确保目录存在
    - file: dest=/etc/fooapp state=directory

    # 拷贝所有匹配Pattern的文件
    - copy: src={{ item }} dest=/etc/fooapp/ owner=root mode=600
      with_fileglob:
        - /playbooks/files/fooapp/*

---
alpha: [ 'a', 'b', 'c', 'd' ]
numbers:  [ 1, 2, 3, 4 ]



tasks:
    - debug: msg="{{ item.0 }} and {{ item.1 }}"
      with_together:
        - "{{alpha}}"
        - "{{numbers}}"

- name: indexed loop demo
  debug: msg="at array position {{ item.0 }} there is a value {{ item.1 }}"
  with_indexed_items: "{{some_list}}"

可以从列表中随机选取一组值，然后循环：

- debug: msg={{ item }}
  with_random_choice:
     - "go through the door"
     - "drink from the goblet"
     - "press the red button"
     - "do nothing"

---
- hosts: all

  tasks:

    # create groups
    - group: name=evens state=present
    - group: name=odds state=present

    - user: name={{ item }} state=present groups=evens
      #              起      止      格式化item
      with_sequence: start=0 end=32 format=testuser%02x

    - file: dest=/var/stuff/{{ item }} state=directory
      #                             步进
      with_sequence: start=4 end=16 stride=2


    - group: name=group{{ item }} state=present
      with_sequence: count=4

- action: shell /usr/bin/foo
  # 结果注册为变量
  register: result
  # 循环判断
  until: result.stdout.find("all systems go") != -1
  # 最大重试次数和延迟
  retries: 5
  delay: 10

- name: Example of looping over a command result
  shell: /usr/bin/frobnicate {{ item }}
  with_lines: /usr/bin/frobnications_per_host --param {{ inventory_hostname }}

默认情况下playbook中的任务执行时会一直保持连接，直到该任务在每个节点都执行完毕。

对于长时间运行的任务，可以一起异步发动，然后进行轮询，来判断是否结束。

- hosts: all
  remote_user: root

  tasks:

  - name: simulate long running op (15 sec), wait for up to 45 sec, poll every 5 sec
    command: /bin/sleep 15
    # 异步等待45s
    async: 45
    # 每5s检查一下
    poll: 5

默认情况下，一旦出现错误，后续任务就不在该主机上运行，可以改变此行为：

- name: this will not be counted as a failure
  command: /bin/false

默认情况下，退出码决定是否失败，你可以修改为基于stderr判断：

- name: this command prints FAILED when it fails
  command: /usr/bin/example-command -x -y -z
  register: command_result
  failed_when: "'FAILED' in command_result.stderr"

前面提到过Tags，它的作用是，仅仅运行Playbook的一部分。 

# 可以对include添加tag
include: foo.yml tags=web,foo
tasks:
    
    - yum: name={{ item }} state=installed
      with_items:
         - httpd
         - memcached
      tags:
         - packages

    - template: src=templates/src.j2 dest=/etc/foo.conf
      tags:
         - configuration

# 仅仅执行具有某些标签的任务
ansible-playbook example.yml --tags "configuration,packages"

# 跳过具有特定标签的任务
ansible-playbook example.yml --skip-tags "notification"

Ansible支持两个特殊标签：

1. always，具有这种标签的role或play总是会运行，除非明确给出

   --skip-tags always

2. never，具有这种标签的role不会执行，除非明确给出

   --tags never

Ansible 1.5的新版本中，作为Vault Ansible 的一项新功能可将例如passwords、keys等敏感数据文件进行加密，而非存放在明文的 playbooks 或 roles 中。这些 vault 文件可以分散存放也可以集中存放。

创建加密文件：

ansible-vault create foo.yml

你需要指定密码，算法AES。未来使用Vault时需要该密码。包括编辑、查看它时：

ansible-vault edit foo.yml
ansible-vault view foo.yml bar.yml baz.yml

可以修改、批量修改多个Vault的密码：

ansible-vault rekey foo.yml bar.yml baz.yml

解密：

ansible-vault decrypt foo.yml bar.yml baz.yml

#                         询问Vault密码
ansible-playbook site.yml --ask-vault-pass

# 密码可以存放在文件或脚本中
ansible-playbook site.yml --vault-password-file ~/.vault_pass.txt
ansible-playbook site.yml --vault-password-file ~/.vault_pass.py

过滤器输入显示为第一个参数：

{{ my_variable|default('my_variable is not defined') }}

{{ ''|default('the string was empty', true) }}

{{ "%s - %s"|format("Hello?", "Foo!") }} 

{{ [1, 2, 3]|join('|') }}

{{ "Hello World"|replace("Hello", "Goodbye") }}
    -> Goodbye World

{{ numbers|select("odd") }} 

{% for item in iterable|sort %}
    ...
{% endfor %}

{{ "foo bar"|truncate(5) }}
    -> "foo ..."
{{ "foo bar"|truncate(5, True) }}
    -> "foo b..."

对于测试

test(arg,arg1,arg2...)

{% if arg is test(arg1,arg2...) %}

{% for number in range(10 - users|count) %}
    <li class="empty"><span>...</span></li>
{% endfor %} 

{'foo' : 'bar'}

(foo=bar)

要在模板中插入一段表达式，需要使用双括号

{{ expr }}

要在模板中插入一段语句，需要使用

{% statement%}

注释语法为：

{#  #}

要转义双括号，可以使用：

{{ '{{' }}

对于大段文本，需要保持原样，可以：

{% raw %}
    <ul>
    {% for item in seq %}
        <li>{{ item }}</li>
    {% endfor %}
    </ul>
{% endraw %} 

{{

{{

"Hello World"

42

42.23

[ 'list',  'of', 'objects' ]

( 'tuple', 'of', 'values' )

{ 'dict': 'of', 'key': 'and', 'value': 'pairs' }

true

false

支持下标和点号两种导航语法：

{{ foo.bar }}
{{ foo['bar'] }}

可以使用过滤器修改变量，过滤器和变量之间用管道符号 | 分隔，过滤器可以链式调用，前一个的输出，是后一个的输入：

{{ name|striptags|title }}

过滤器支持参数，参数需要放在括号中： 

{{ list|join(', ') }}

{% set pipe = joiner("|") %} 

可以用 - 符号提示，需要将定界符左侧或右侧的空白移除：

# 移除右侧
{% for item in seq -%}
    {{ item }}
{%- endfor %}
# 移除左侧

 要测试一个变量或表达式，你要在变量后加上一个 is 以及测试的名称：

# 测试变量是否定义
{% if name is defined %}

# 测试是否可以整除
{% if loop.index is divisibleby 3 %}
{% if loop.index is divisibleby(3) %}


# if-elif-else

{% if kenny.sick %}
    Kenny is sick.
{% elif kenny.dead %}
    You killed Kenny!  You bastard!!!
{% else %}
    Kenny looks okay --- so far
{% endif %}

# 迭代列表
{% for user in users %}
  <li>{{ user.username|e }}</li>
{% endfor %}

# 迭代字典
{% for key, value in my_dict.iteritems() %}
    <dt>{{ key|e }}</dt>
    <dd>{{ value|e }}</dd>
{% endfor %}

用于新建一个作用域：

{% with %}
    {% set foo = 42 %}
    {{ foo }}           foo is 42 here
{% endwith %}
foo is not visible here any longer

- name: Rendering init service job tempalte to local directory
  vars:
    download-script: "{{ lookup('file', 'files/download.sh') }}"
  template:
    src: "init.yaml.j2"
    dest: "{{ role_path }}/files/init-{{item.name}}.yaml"
  with_items: "{{ services }}"

在上面的模板init.yaml.j2中，你可以直接引用变量download-script：

apiVersion: batch/v1
kind: Job
metadata:
  name: init-{{ item.name }}
spec:
  template:
    spec:
      containers:
      - command:
        - /bin/bash
        - -c
        - |
{{ download_script | indent( width=10, indentfirst=True) }}

使用indent函数，参考上面。 

The post Ansible学习笔记 appeared first on 绿色记忆.