diff --git a/.github/workflows/hugo.yml b/.github/workflows/hugo.yml deleted file mode 100644 index cffaec5..0000000 --- a/.github/workflows/hugo.yml +++ /dev/null @@ -1,70 +0,0 @@ -# Sample workflow for building and deploying a Hugo site to GitHub Pages -name: Deploy Hugo site to Pages - -on: - # Runs on pushes targeting the default branch - push: - branches: ["main"] - - # Allows you to run this workflow manually from the Actions tab - workflow_dispatch: - -# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages -permissions: - contents: read - pages: write - id-token: write - -# Allow one concurrent deployment -concurrency: - group: "pages" - cancel-in-progress: true - -# Default to bash -defaults: - run: - shell: bash - -jobs: - # Build job - build: - runs-on: ubuntu-latest - env: - HUGO_VERSION: 0.102.3 - steps: - - name: Install Hugo CLI - run: | - wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_Linux-64bit.deb \ - && sudo dpkg -i ${{ runner.temp }}/hugo.deb - - name: Checkout - uses: actions/checkout@v3 - with: - submodules: recursive - - name: Setup Pages - id: pages - uses: actions/configure-pages@v2 - - name: Build with Hugo - env: - # For maximum backward compatibility with Hugo modules - HUGO_ENVIRONMENT: production - HUGO_ENV: production - run: | - hugo \ - --minify \ - --baseURL "${{ steps.pages.outputs.base_url }}/" - - name: Upload artifact - uses: actions/upload-pages-artifact@v1 - with: - path: ./public - - # Deployment job - deploy: - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - runs-on: ubuntu-latest - needs: build - steps: - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v1 diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml new file mode 100644 index 0000000..439158f --- /dev/null +++ b/.github/workflows/main.yml @@ -0,0 +1,26 @@ +name: CI + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + build: + name: Deploy gh-pages + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + steps: + - uses: actions/checkout@v3.3.0 + - uses: actions-rs/toolchain@v1 + with: + toolchain: stable + - run: (test -x $HOME/.cargo/bin/mdbook || cargo install mdbook) + - run: mdbook build && mdbook test + - uses: JamesIves/github-pages-deploy-action@v4.4.1 + with: + branch: gh-pages + folder: book diff --git a/.gitignore b/.gitignore index c6127b3..9483019 100644 --- a/.gitignore +++ b/.gitignore @@ -47,6 +47,7 @@ *.cmd .tmp_versions/ modules.order +book Module.symvers Mkfile.old dkms.conf diff --git a/2-kprobe-unlink/ecli b/2-kprobe-unlink/ecli deleted file mode 100755 index 275c42d..0000000 Binary files a/2-kprobe-unlink/ecli and /dev/null differ diff --git a/book.toml b/book.toml new file mode 100644 index 0000000..432b20f --- /dev/null +++ b/book.toml @@ -0,0 +1,6 @@ +[book] +authors = ["eunomia-bpf"] +language = "en" +multilingual = false +src = "src" +title = "bpf-developer-tutorial" diff --git a/0-introduce/README.md b/src/0-introduce/README.md similarity index 100% rename from 0-introduce/README.md rename to src/0-introduce/README.md diff --git a/0-introduce/kernel-arch.webp b/src/0-introduce/kernel-arch.webp similarity index 100% rename from 0-introduce/kernel-arch.webp rename to src/0-introduce/kernel-arch.webp diff --git a/0-introduce/new-os-model.jpg b/src/0-introduce/new-os-model.jpg similarity index 100% rename from 0-introduce/new-os-model.jpg rename to src/0-introduce/new-os-model.jpg diff --git a/1-helloworld/.gitignore b/src/1-helloworld/.gitignore similarity index 100% rename from 1-helloworld/.gitignore rename to src/1-helloworld/.gitignore diff --git a/1-helloworld/README.md b/src/1-helloworld/README.md similarity index 100% rename from 1-helloworld/README.md rename to src/1-helloworld/README.md diff --git a/1-helloworld/minimal.bpf.c b/src/1-helloworld/minimal.bpf.c similarity index 100% rename from 1-helloworld/minimal.bpf.c rename to src/1-helloworld/minimal.bpf.c diff --git a/10-hardirqs/.gitignore b/src/10-hardirqs/.gitignore similarity index 100% rename from 10-hardirqs/.gitignore rename to src/10-hardirqs/.gitignore diff --git a/10-hardirqs/README.md b/src/10-hardirqs/README.md similarity index 100% rename from 10-hardirqs/README.md rename to src/10-hardirqs/README.md diff --git a/10-hardirqs/bits.bpf.h b/src/10-hardirqs/bits.bpf.h similarity index 100% rename from 10-hardirqs/bits.bpf.h rename to src/10-hardirqs/bits.bpf.h diff --git a/10-hardirqs/hardirqs.bpf.c b/src/10-hardirqs/hardirqs.bpf.c similarity index 100% rename from 10-hardirqs/hardirqs.bpf.c rename to src/10-hardirqs/hardirqs.bpf.c diff --git a/10-hardirqs/hardirqs.h b/src/10-hardirqs/hardirqs.h similarity index 100% rename from 10-hardirqs/hardirqs.h rename to src/10-hardirqs/hardirqs.h diff --git a/10-hardirqs/maps.bpf.h b/src/10-hardirqs/maps.bpf.h similarity index 100% rename from 10-hardirqs/maps.bpf.h rename to src/10-hardirqs/maps.bpf.h diff --git a/11-bootstrap/.gitignore b/src/11-bootstrap/.gitignore similarity index 100% rename from 11-bootstrap/.gitignore rename to src/11-bootstrap/.gitignore diff --git a/11-bootstrap/README.md b/src/11-bootstrap/README.md similarity index 100% rename from 11-bootstrap/README.md rename to src/11-bootstrap/README.md diff --git a/11-bootstrap/bootstrap.bpf.c b/src/11-bootstrap/bootstrap.bpf.c similarity index 100% rename from 11-bootstrap/bootstrap.bpf.c rename to src/11-bootstrap/bootstrap.bpf.c diff --git a/11-bootstrap/bootstrap.h b/src/11-bootstrap/bootstrap.h similarity index 100% rename from 11-bootstrap/bootstrap.h rename to src/11-bootstrap/bootstrap.h diff --git a/12-profile/README.md b/src/12-profile/README.md similarity index 100% rename from 12-profile/README.md rename to src/12-profile/README.md diff --git a/13-tcpconnlat/.gitignore b/src/13-tcpconnlat/.gitignore similarity index 100% rename from 13-tcpconnlat/.gitignore rename to src/13-tcpconnlat/.gitignore diff --git a/13-tcpconnlat/README.md b/src/13-tcpconnlat/README.md similarity index 100% rename from 13-tcpconnlat/README.md rename to src/13-tcpconnlat/README.md diff --git a/13-tcpconnlat/libbpf-bootstrap/tcpconnlat.bpf.c b/src/13-tcpconnlat/libbpf-bootstrap/tcpconnlat.bpf.c similarity index 100% rename from 13-tcpconnlat/libbpf-bootstrap/tcpconnlat.bpf.c rename to src/13-tcpconnlat/libbpf-bootstrap/tcpconnlat.bpf.c diff --git a/13-tcpconnlat/libbpf-bootstrap/tcpconnlat.c b/src/13-tcpconnlat/libbpf-bootstrap/tcpconnlat.c similarity index 100% rename from 13-tcpconnlat/libbpf-bootstrap/tcpconnlat.c rename to src/13-tcpconnlat/libbpf-bootstrap/tcpconnlat.c diff --git a/13-tcpconnlat/libbpf-bootstrap/tcpconnlat.h b/src/13-tcpconnlat/libbpf-bootstrap/tcpconnlat.h similarity index 100% rename from 13-tcpconnlat/libbpf-bootstrap/tcpconnlat.h rename to src/13-tcpconnlat/libbpf-bootstrap/tcpconnlat.h diff --git a/13-tcpconnlat/tcpconnlat.bpf.c b/src/13-tcpconnlat/tcpconnlat.bpf.c similarity index 100% rename from 13-tcpconnlat/tcpconnlat.bpf.c rename to src/13-tcpconnlat/tcpconnlat.bpf.c diff --git a/13-tcpconnlat/tcpconnlat.bpf.h b/src/13-tcpconnlat/tcpconnlat.bpf.h similarity index 100% rename from 13-tcpconnlat/tcpconnlat.bpf.h rename to src/13-tcpconnlat/tcpconnlat.bpf.h diff --git a/13-tcpconnlat/tcpconnlat.md b/src/13-tcpconnlat/tcpconnlat.md similarity index 100% rename from 13-tcpconnlat/tcpconnlat.md rename to src/13-tcpconnlat/tcpconnlat.md diff --git a/13-tcpconnlat/tcpconnlat1.png b/src/13-tcpconnlat/tcpconnlat1.png similarity index 100% rename from 13-tcpconnlat/tcpconnlat1.png rename to src/13-tcpconnlat/tcpconnlat1.png diff --git a/13-tcpconnlat/tcpconnlat_p.png b/src/13-tcpconnlat/tcpconnlat_p.png similarity index 100% rename from 13-tcpconnlat/tcpconnlat_p.png rename to src/13-tcpconnlat/tcpconnlat_p.png diff --git a/14-tcpstates/.gitignore b/src/14-tcpstates/.gitignore similarity index 100% rename from 14-tcpstates/.gitignore rename to src/14-tcpstates/.gitignore diff --git a/14-tcpstates/README.md b/src/14-tcpstates/README.md similarity index 100% rename from 14-tcpstates/README.md rename to src/14-tcpstates/README.md diff --git a/14-tcpstates/libbpf-bootstrap/tcpstates.bpf.c b/src/14-tcpstates/libbpf-bootstrap/tcpstates.bpf.c similarity index 100% rename from 14-tcpstates/libbpf-bootstrap/tcpstates.bpf.c rename to src/14-tcpstates/libbpf-bootstrap/tcpstates.bpf.c diff --git a/14-tcpstates/libbpf-bootstrap/tcpstates.c b/src/14-tcpstates/libbpf-bootstrap/tcpstates.c similarity index 100% rename from 14-tcpstates/libbpf-bootstrap/tcpstates.c rename to src/14-tcpstates/libbpf-bootstrap/tcpstates.c diff --git a/14-tcpstates/libbpf-bootstrap/tcpstates.h b/src/14-tcpstates/libbpf-bootstrap/tcpstates.h similarity index 100% rename from 14-tcpstates/libbpf-bootstrap/tcpstates.h rename to src/14-tcpstates/libbpf-bootstrap/tcpstates.h diff --git a/14-tcpstates/tcpstates.bpf.c b/src/14-tcpstates/tcpstates.bpf.c similarity index 100% rename from 14-tcpstates/tcpstates.bpf.c rename to src/14-tcpstates/tcpstates.bpf.c diff --git a/14-tcpstates/tcpstates.bpf.h b/src/14-tcpstates/tcpstates.bpf.h similarity index 100% rename from 14-tcpstates/tcpstates.bpf.h rename to src/14-tcpstates/tcpstates.bpf.h diff --git a/15-tcprtt/README.md b/src/15-tcprtt/README.md similarity index 100% rename from 15-tcprtt/README.md rename to src/15-tcprtt/README.md diff --git a/16-memleak/README.md b/src/16-memleak/README.md similarity index 100% rename from 16-memleak/README.md rename to src/16-memleak/README.md diff --git a/17-biopattern/README.md b/src/17-biopattern/README.md similarity index 100% rename from 17-biopattern/README.md rename to src/17-biopattern/README.md diff --git a/18-further-reading/README.md b/src/18-further-reading/README.md similarity index 100% rename from 18-further-reading/README.md rename to src/18-further-reading/README.md diff --git a/19-lsm-connect/.gitignore b/src/19-lsm-connect/.gitignore similarity index 100% rename from 19-lsm-connect/.gitignore rename to src/19-lsm-connect/.gitignore diff --git a/19-lsm-connect/README.md b/src/19-lsm-connect/README.md similarity index 100% rename from 19-lsm-connect/README.md rename to src/19-lsm-connect/README.md diff --git a/19-lsm-connect/lsm-connect.bpf.c b/src/19-lsm-connect/lsm-connect.bpf.c similarity index 100% rename from 19-lsm-connect/lsm-connect.bpf.c rename to src/19-lsm-connect/lsm-connect.bpf.c diff --git a/2-kprobe-unlink/.gitignore b/src/2-kprobe-unlink/.gitignore similarity index 100% rename from 2-kprobe-unlink/.gitignore rename to src/2-kprobe-unlink/.gitignore diff --git a/2-kprobe-unlink/README.md b/src/2-kprobe-unlink/README.md similarity index 100% rename from 2-kprobe-unlink/README.md rename to src/2-kprobe-unlink/README.md diff --git a/2-kprobe-unlink/kprobe-link.bpf.c b/src/2-kprobe-unlink/kprobe-link.bpf.c similarity index 100% rename from 2-kprobe-unlink/kprobe-link.bpf.c rename to src/2-kprobe-unlink/kprobe-link.bpf.c diff --git a/20-tc/.gitignore b/src/20-tc/.gitignore similarity index 100% rename from 20-tc/.gitignore rename to src/20-tc/.gitignore diff --git a/20-tc/README.md b/src/20-tc/README.md similarity index 100% rename from 20-tc/README.md rename to src/20-tc/README.md diff --git a/20-tc/tc.bpf.c b/src/20-tc/tc.bpf.c similarity index 100% rename from 20-tc/tc.bpf.c rename to src/20-tc/tc.bpf.c diff --git a/21-xdp/README.md b/src/21-xdp/README.md similarity index 100% rename from 21-xdp/README.md rename to src/21-xdp/README.md diff --git a/3-fentry-unlink/.gitignore b/src/3-fentry-unlink/.gitignore similarity index 100% rename from 3-fentry-unlink/.gitignore rename to src/3-fentry-unlink/.gitignore diff --git a/3-fentry-unlink/README.md b/src/3-fentry-unlink/README.md similarity index 100% rename from 3-fentry-unlink/README.md rename to src/3-fentry-unlink/README.md diff --git a/3-fentry-unlink/fentry-link.bpf.c b/src/3-fentry-unlink/fentry-link.bpf.c similarity index 100% rename from 3-fentry-unlink/fentry-link.bpf.c rename to src/3-fentry-unlink/fentry-link.bpf.c diff --git a/4-opensnoop/.gitignore b/src/4-opensnoop/.gitignore similarity index 100% rename from 4-opensnoop/.gitignore rename to src/4-opensnoop/.gitignore diff --git a/4-opensnoop/README.md b/src/4-opensnoop/README.md similarity index 100% rename from 4-opensnoop/README.md rename to src/4-opensnoop/README.md diff --git a/4-opensnoop/opensnoop.bpf.c b/src/4-opensnoop/opensnoop.bpf.c similarity index 100% rename from 4-opensnoop/opensnoop.bpf.c rename to src/4-opensnoop/opensnoop.bpf.c diff --git a/5-uprobe-bashreadline/.gitignore b/src/5-uprobe-bashreadline/.gitignore similarity index 100% rename from 5-uprobe-bashreadline/.gitignore rename to src/5-uprobe-bashreadline/.gitignore diff --git a/5-uprobe-bashreadline/README.md b/src/5-uprobe-bashreadline/README.md similarity index 100% rename from 5-uprobe-bashreadline/README.md rename to src/5-uprobe-bashreadline/README.md diff --git a/5-uprobe-bashreadline/bashreadline.bpf.c b/src/5-uprobe-bashreadline/bashreadline.bpf.c similarity index 100% rename from 5-uprobe-bashreadline/bashreadline.bpf.c rename to src/5-uprobe-bashreadline/bashreadline.bpf.c diff --git a/6-sigsnoop/.gitignore b/src/6-sigsnoop/.gitignore similarity index 100% rename from 6-sigsnoop/.gitignore rename to src/6-sigsnoop/.gitignore diff --git a/6-sigsnoop/README.md b/src/6-sigsnoop/README.md similarity index 100% rename from 6-sigsnoop/README.md rename to src/6-sigsnoop/README.md diff --git a/6-sigsnoop/sigsnoop.bpf.c b/src/6-sigsnoop/sigsnoop.bpf.c similarity index 100% rename from 6-sigsnoop/sigsnoop.bpf.c rename to src/6-sigsnoop/sigsnoop.bpf.c diff --git a/7-execsnoop/.gitignore b/src/7-execsnoop/.gitignore similarity index 100% rename from 7-execsnoop/.gitignore rename to src/7-execsnoop/.gitignore diff --git a/7-execsnoop/README.md b/src/7-execsnoop/README.md similarity index 100% rename from 7-execsnoop/README.md rename to src/7-execsnoop/README.md diff --git a/7-execsnoop/execsnoop.bpf.c b/src/7-execsnoop/execsnoop.bpf.c similarity index 100% rename from 7-execsnoop/execsnoop.bpf.c rename to src/7-execsnoop/execsnoop.bpf.c diff --git a/7-execsnoop/execsnoop.h b/src/7-execsnoop/execsnoop.h similarity index 100% rename from 7-execsnoop/execsnoop.h rename to src/7-execsnoop/execsnoop.h diff --git a/8-exitsnoop/.gitignore b/src/8-exitsnoop/.gitignore similarity index 100% rename from 8-exitsnoop/.gitignore rename to src/8-exitsnoop/.gitignore diff --git a/8-exitsnoop/README.md b/src/8-exitsnoop/README.md similarity index 100% rename from 8-exitsnoop/README.md rename to src/8-exitsnoop/README.md diff --git a/8-exitsnoop/exitsnoop.bpf.c b/src/8-exitsnoop/exitsnoop.bpf.c similarity index 100% rename from 8-exitsnoop/exitsnoop.bpf.c rename to src/8-exitsnoop/exitsnoop.bpf.c diff --git a/8-exitsnoop/exitsnoop.h b/src/8-exitsnoop/exitsnoop.h similarity index 100% rename from 8-exitsnoop/exitsnoop.h rename to src/8-exitsnoop/exitsnoop.h diff --git a/9-runqlat/.gitignore b/src/9-runqlat/.gitignore similarity index 100% rename from 9-runqlat/.gitignore rename to src/9-runqlat/.gitignore diff --git a/9-runqlat/README.md b/src/9-runqlat/README.md similarity index 100% rename from 9-runqlat/README.md rename to src/9-runqlat/README.md diff --git a/9-runqlat/bits.bpf.h b/src/9-runqlat/bits.bpf.h similarity index 100% rename from 9-runqlat/bits.bpf.h rename to src/9-runqlat/bits.bpf.h diff --git a/9-runqlat/core_fixes.bpf.h b/src/9-runqlat/core_fixes.bpf.h similarity index 100% rename from 9-runqlat/core_fixes.bpf.h rename to src/9-runqlat/core_fixes.bpf.h diff --git a/9-runqlat/maps.bpf.h b/src/9-runqlat/maps.bpf.h similarity index 100% rename from 9-runqlat/maps.bpf.h rename to src/9-runqlat/maps.bpf.h diff --git a/9-runqlat/runqlat.bpf.c b/src/9-runqlat/runqlat.bpf.c similarity index 100% rename from 9-runqlat/runqlat.bpf.c rename to src/9-runqlat/runqlat.bpf.c diff --git a/9-runqlat/runqlat.h b/src/9-runqlat/runqlat.h similarity index 100% rename from 9-runqlat/runqlat.h rename to src/9-runqlat/runqlat.h diff --git a/src/SUMMARY.md b/src/SUMMARY.md new file mode 100644 index 0000000..007d623 --- /dev/null +++ b/src/SUMMARY.md @@ -0,0 +1,37 @@ +# Summary + +# eBPF 入门开发实践教程 + +- [eBPF 入门开发实践教程一:介绍 eBPF 的基本概念、常见的开发工具](0-introduce/README.md) +- [eBPF 入门开发实践教程二:Hello World,基本框架和开发流程](1-helloworld/README.md) +- [eBPF 入门开发实践教程二:在 eBPF 中使用 kprobe 监测捕获 unlink 系统调用](2-kprobe-unlink/README.md) +- [eBPF 入门开发实践教程三:在 eBPF 中使用 fentry 监测捕获 unlink 系统调用](3-fentry-unlink/README.md) +- [eBPF 入门开发实践教程四:在 eBPF 中捕获进程打开文件的系统调用集合,使用全局变量过滤进程 pid](4-opensnoop/README.md) +- [eBPF 入门开发实践教程五:在 eBPF 中使用 uprobe 捕获 bash 的 readline 函数调用](5-uprobe-bashreadline/README.md) +- [eBPF 入门开发实践教程六:捕获进程发送信号的系统调用集合,使用 hash map 保存状态](6-sigsnoop/README.md) +- [eBPF 入门实践教程七:捕获进程执行/退出时间,通过 perf event array 向用户态打印输出](7-execsnoop/README.md) +- [eBPF 入门开发实践教程八:在 eBPF 中使用 exitsnoop 监控进程退出事件,使用 ring buffer 向用户态打印输出](8-exitsnoop/README.md) +- [eBPF 入门开发实践教程九:一个 Linux 内核 BPF 程序,通过柱状图来总结调度程序运行队列延迟,显示任务等待运行在 CPU 上的时间长度](9-runqlat/README.md) +- [eBPF 入门开发实践教程十:在 eBPF 中使用 hardirqs 或 softirqs 捕获中断事件](10-hardirqs/README.md) +- [eBPF 入门开发实践教程十一:在 eBPF 中使用 bootstrap 开发用户态程序并跟踪 exec() 和 exit() 系统调用](11-bootstrap/README.md) + +# eBPF入门实践教程 + +- [eBPF入门实践教程:使用 libbpf-bootstrap 开发程序统计 TCP 连接延时](13-tcpconnlat/README.md) +- [eBPF 入门实践教程:编写 eBPF 程序 tcpconnlat 测量 tcp 连接延时](13-tcpconnlat/tcpconnlat.md) +- [eBPF入门实践教程:使用 libbpf-bootstrap 开发程序统计 TCP 连接延时](14-tcpstates/README.md) +- [eBPF 入门实践教程:编写 eBPF 程序 Tcprtt 测量 TCP 连接的往返时间](15-tcprtt/README.md) +- [eBPF 入门实践教程:编写 eBPF 程序 Memleak 监控内存泄漏](16-memleak/README.md) +- [eBPF 入门实践教程:编写 eBPF 程序 Biopattern: 统计随机/顺序磁盘 I/O](17-biopattern/README.md) +- [更多的参考资料](18-further-reading/README.md) +- [eBPF 入门实践教程:使用 LSM 进行安全检测防御](19-lsm-connect/README.md) +- [eBPF 入门实践教程:使用 eBPF 进行 tc 流量控制](20-tc/README.md) + +# bcc Guide + +- [BPF Features by Linux Kernel Version](bcc-documents/kernel-versions.md) +- [Kernel Configuration for BPF Features](bcc-documents/kernel_config.md) +- [bcc Reference Guide](bcc-documents/reference_guide.md) +- [Special Filtering](bcc-documents/special_filtering.md) +- [bcc Tutorial](bcc-documents/tutorial.md) +- [bcc Python Developer Tutorial](bcc-documents/tutorial_bcc_python_developer.md) diff --git a/bcc-documents/kernel-versions.md b/src/bcc-documents/kernel-versions.md similarity index 99% rename from bcc-documents/kernel-versions.md rename to src/bcc-documents/kernel-versions.md index 23a9c55..7f65eab 100644 --- a/bcc-documents/kernel-versions.md +++ b/src/bcc-documents/kernel-versions.md @@ -9,8 +9,9 @@ Kernel version | Commit ## JIT compiling The list of supported architectures for your kernel can be retrieved with: - - git grep HAVE_EBPF_JIT arch/ +```sh +git grep HAVE_EBPF_JIT arch/ +``` Feature / Architecture | Kernel version | Commit -----------------------|----------------|------- @@ -34,8 +35,9 @@ LoongArch | 6.1 | [`5dc615520c4d`](https://github.com/ Several (but not all) of these _main features_ translate to an eBPF program type. The list of such program types supported in your kernel can be found in file [`include/uapi/linux/bpf.h`](https://github.com/torvalds/linux/blob/master/include/uapi/linux/bpf.h): - - git grep -W 'bpf_prog_type {' include/uapi/linux/bpf.h +```sh +git grep -W 'bpf_prog_type {' include/uapi/linux/bpf.h +``` Feature | Kernel version | Commit --------|----------------|------- @@ -133,8 +135,9 @@ Allow executing syscalls | 5.15 | [`79a7f8bdb159`](https://github.com/torv The list of map types supported in your kernel can be found in file [`include/uapi/linux/bpf.h`](https://github.com/torvalds/linux/blob/master/include/uapi/linux/bpf.h): - - git grep -W 'bpf_map_type {' include/uapi/linux/bpf.h +```sh +git grep -W 'bpf_map_type {' include/uapi/linux/bpf.h +``` Map type | Kernel version | Commit | Enum ----------|----------------|--------|------ @@ -175,8 +178,9 @@ user ringbuf | 6.1 | [`583c1f420173`](https://github.com/tor Some (but not all) of these *API features* translate to a subcommand beginning with `BPF_MAP_`. The list of subcommands supported in your kernel can be found in file [`include/uapi/linux/bpf.h`](https://github.com/torvalds/linux/blob/master/include/uapi/linux/bpf.h): - - git grep -W 'bpf_cmd {' include/uapi/linux/bpf.h +```sh +git grep -W 'bpf_cmd {' include/uapi/linux/bpf.h +``` Feature | Kernel version | Commit --------|----------------|------- @@ -202,8 +206,9 @@ mmap() support for array maps | 5.5 | [`fc9702273e2e`](https://github.com/torval An approximate list of drivers or components supporting XDP programs for your kernel can be retrieved with: - - git grep -l XDP_SETUP_PROG drivers/ +```sh +git grep -l XDP_SETUP_PROG drivers/ +``` Feature / Driver | Kernel version | Commit -----------------|----------------|------- @@ -241,8 +246,9 @@ Intel `igb` driver | 5.10 | [`9cbc948b5a20`](https://github.com/torvalds/linux/c The list of helpers supported in your kernel can be found in file [`include/uapi/linux/bpf.h`](https://github.com/torvalds/linux/blob/master/include/uapi/linux/bpf.h): - - git grep ' FN(' include/uapi/linux/bpf.h +```sh +git grep ' FN(' include/uapi/linux/bpf.h +``` Alphabetical order @@ -473,8 +479,9 @@ Check the list of GPL-compatible licenses in your [kernel source code](https://g ## Program Types The list of program types and supported helper functions can be retrieved with: - - git grep -W 'func_proto(enum bpf_func_id func_id' kernel/ net/ drivers/ +```sh +git grep -W 'func_proto(enum bpf_func_id func_id' kernel/ net/ drivers/ +``` |Program Type| Helper Functions| |------------|-----------------| diff --git a/bcc-documents/kernel_config.md b/src/bcc-documents/kernel_config.md similarity index 100% rename from bcc-documents/kernel_config.md rename to src/bcc-documents/kernel_config.md diff --git a/bcc-documents/reference_guide.md b/src/bcc-documents/reference_guide.md similarity index 99% rename from bcc-documents/reference_guide.md rename to src/bcc-documents/reference_guide.md index 8ac898b..8543a0c 100644 --- a/bcc-documents/reference_guide.md +++ b/src/bcc-documents/reference_guide.md @@ -155,7 +155,7 @@ Arguments are specified on the function declaration: kprobe__*kernel_function_na For example: -```C +```c int kprobe__tcp_v4_connect(struct pt_regs *ctx, struct sock *sk) { [...] } @@ -1457,7 +1457,7 @@ Syntax: ```int map.sock_hash_update(struct bpf_sock_ops *skops, &key, int flags) Add an entry to, or update a sockhash map referencing sockets. The skops is used as a new value for the entry associated to key. flags is one of: -``` +```sh BPF_NOEXIST: The entry for key must not exist in the map. BPF_EXIST: The entry for key must already exist in the map. BPF_ANY: No condition on the existence of the entry for key. @@ -2279,7 +2279,7 @@ b["dist"].print_log2_hist("kbytes") Output: -``` +```sh kbytes : count distribution 0 -> 1 : 3 | | 2 -> 3 : 0 | | @@ -2330,7 +2330,7 @@ b["dist"].print_linear_hist("kbytes") Output: -``` +```sh kbytes : count distribution 0 : 3 |****** | 1 : 0 | | @@ -2495,7 +2495,7 @@ Translate a memory address into a function name for a pid, which is returned. A Example: -```Python +```python print("function: " + b.sym(addr, pid)) ``` @@ -2511,7 +2511,7 @@ Returns the number of open k[ret]probes. Can be useful for scenarios where event Example: -```Python +```python b.attach_kprobe(event_re=pattern, fn_name="trace_count") matched = b.num_open_kprobes() if matched == 0: @@ -2531,7 +2531,7 @@ Return the corresponding kernel function name of the syscall. This helper functi Example: -```Python +```python print("The function name of %s in kernel is %s" % ("clone", b.get_syscall_fnname("clone"))) # sys_clone or __x64_sys_clone or ... ``` @@ -2550,7 +2550,7 @@ This can be due to trying to read memory directly, instead of operating on memor Example: -``` +```sh bpf: Permission denied 0: (bf) r6 = r1 1: (79) r7 = *(u64 *)(r6 +80) @@ -2578,7 +2578,7 @@ This error happens when a GPL-only helper is called from a non-GPL BPF program. Example calling `bpf_get_stackid()`, a GPL-only BPF helper, from a proprietary program (`#define BPF_LICENSE Proprietary`): -``` +```sh bpf: Failed to load program: Invalid argument [...] 8: (85) call bpf_get_stackid#27 diff --git a/bcc-documents/special_filtering.md b/src/bcc-documents/special_filtering.md similarity index 97% rename from bcc-documents/special_filtering.md rename to src/bcc-documents/special_filtering.md index 9b15260..c109f0c 100644 --- a/bcc-documents/special_filtering.md +++ b/src/bcc-documents/special_filtering.md @@ -11,7 +11,7 @@ map managed externally. Examples of commands: -``` +```sh # ./opensnoop --cgroupmap /sys/fs/bpf/test01 # ./execsnoop --cgroupmap /sys/fs/bpf/test01 # ./tcpconnect --cgroupmap /sys/fs/bpf/test01 @@ -25,14 +25,14 @@ pinned BPF hash map. The BPF hash map can be created by: -``` +```sh # bpftool map create /sys/fs/bpf/test01 type hash key 8 value 8 entries 128 \ name cgroupset flags 0 ``` To get a shell in a new cgroup, you can use: -``` +```sh # systemd-run --pty --unit test bash ``` @@ -43,7 +43,7 @@ The cgroup id can be discovered using the `name_to_handle_at()` system call. In the examples/cgroupid, you will find an example of program to get the cgroup id. -``` +```sh # cd examples/cgroupid # make # ./cgroupid hex /sys/fs/cgroup/unified/system.slice/test.service @@ -51,7 +51,7 @@ id. or, using Docker: -``` +```sh # cd examples/cgroupid # docker build -t cgroupid . # docker run --rm --privileged -v /sys/fs/cgroup:/sys/fs/cgroup \ @@ -61,7 +61,7 @@ or, using Docker: This prints the cgroup id as a hexadecimal string in the host endianness such as `77 16 00 00 01 00 00 00`. -``` +```sh # FILE=/sys/fs/bpf/test01 # CGROUPID_HEX="77 16 00 00 01 00 00 00" # bpftool map update pinned $FILE key hex $CGROUPID_HEX value hex 00 00 00 00 00 00 00 00 any @@ -77,7 +77,7 @@ This feature is useful for integrating bcc tools in external projects. The BPF hash map can be created by: -``` +```sh # bpftool map create /sys/fs/bpf/mnt_ns_set type hash key 8 value 4 entries 128 \ name mnt_ns_set flags 0 ``` @@ -85,19 +85,19 @@ The BPF hash map can be created by: Execute the `execsnoop` tool filtering only the mount namespaces in `/sys/fs/bpf/mnt_ns_set`: -``` +```sh # tools/execsnoop.py --mntnsmap /sys/fs/bpf/mnt_ns_set ``` Start a terminal in a new mount namespace: -``` +```sh # unshare -m bash ``` Update the hash map with the mount namespace ID of the terminal above: -``` +```sh FILE=/sys/fs/bpf/mnt_ns_set if [ $(printf '\1' | od -dAn) -eq 1 ]; then HOST_ENDIAN_CMD=tac @@ -111,13 +111,13 @@ bpftool map update pinned $FILE key hex $NS_ID_HEX value hex 00 00 00 00 any Execute a command in this terminal: -``` +```sh # ping kinvolk.io ``` You'll see how on the `execsnoop` terminal you started above the call is logged: -``` +```sh # tools/execsnoop.py --mntnsmap /sys/fs/bpf/mnt_ns_set [sudo] password for mvb: PCOMM PID PPID RET ARGS diff --git a/bcc-documents/tutorial.md b/src/bcc-documents/tutorial.md similarity index 99% rename from bcc-documents/tutorial.md rename to src/bcc-documents/tutorial.md index 4a6766a..7fcb01f 100644 --- a/bcc-documents/tutorial.md +++ b/src/bcc-documents/tutorial.md @@ -43,7 +43,7 @@ These tools may be installed on your system under /usr/share/bcc/tools, or you c #### 1.1 execsnoop -``` +```sh # ./execsnoop PCOMM PID RET ARGS supervise 9660 0 ./run @@ -61,7 +61,7 @@ More [examples](https://github.com/iovisor/bcc/tree/master/tools/execsnoop_examp #### 1.2. opensnoop -``` +```sh # ./opensnoop PID COMM FD ERR PATH 1565 redis-server 5 0 /proc/1565/stat @@ -84,7 +84,7 @@ More [examples](https://github.com/iovisor/bcc/tree/master/tools/opensnoop_examp #### 1.3. ext4slower (or btrfs\*, xfs\*, zfs\*) -``` +```sh # ./ext4slower Tracing ext4 operations slower than 10 ms TIME COMM PID T BYTES OFF_KB LAT(ms) FILENAME @@ -105,7 +105,7 @@ More [examples](https://github.com/iovisor/bcc/tree/master/tools/ext4slower_exam #### 1.4. biolatency -``` +```sh # ./biolatency Tracing block device I/O... Hit Ctrl-C to end. ^C @@ -137,7 +137,7 @@ More [examples](https://github.com/iovisor/bcc/tree/master/tools/biolatency_exam #### 1.5. biosnoop -``` +```sh # ./biosnoop TIME(s) COMM PID DISK T SECTOR BYTES LAT(ms) 0.000004001 supervise 1950 xvda1 W 13092560 4096 0.74 @@ -157,7 +157,7 @@ More [examples](https://github.com/iovisor/bcc/tree/master/tools/biosnoop_exampl #### 1.6. cachestat -``` +```sh # ./cachestat HITS MISSES DIRTIES READ_HIT% WRITE_HIT% BUFFERS_MB CACHED_MB 1074 44 13 94.9% 2.9% 1 223 @@ -177,7 +177,7 @@ More [examples](https://github.com/iovisor/bcc/tree/master/tools/cachestat_examp #### 1.7. tcpconnect -``` +```sh # ./tcpconnect PID COMM IP SADDR DADDR DPORT 1479 telnet 4 127.0.0.1 127.0.0.1 23 @@ -196,7 +196,7 @@ More [examples](https://github.com/iovisor/bcc/tree/master/tools/tcpconnect_exam #### 1.8. tcpaccept -``` +```sh # ./tcpaccept PID COMM IP RADDR LADDR LPORT 907 sshd 4 192.168.56.1 192.168.56.102 22 @@ -213,7 +213,7 @@ More [examples](https://github.com/iovisor/bcc/tree/master/tools/tcpaccept_examp #### 1.9. tcpretrans -``` +```sh # ./tcpretrans TIME PID IP LADDR:LPORT T> RADDR:RPORT STATE 01:55:05 0 4 10.153.223.157:22 R> 69.53.245.40:34619 ESTABLISHED @@ -230,7 +230,7 @@ More [examples](https://github.com/iovisor/bcc/tree/master/tools/tcpretrans_exam #### 1.10. runqlat -``` +```sh # ./runqlat Tracing run queue latency... Hit Ctrl-C to end. ^C @@ -261,7 +261,7 @@ More [examples](https://github.com/iovisor/bcc/tree/master/tools/runqlat_example #### 1.11. profile -``` +```sh # ./profile Sampling at 49 Hertz of all threads by user + kernel stack... Hit Ctrl-C to end. ^C @@ -322,7 +322,7 @@ These generic tools may be useful to provide visibility to solve your specific p Suppose you want to track file ownership change. There are three syscalls, `chown`, `fchown` and `lchown` which users can use to change file ownership. The corresponding syscall entry is `SyS_[f|l]chown`. The following command can be used to print out syscall parameters and the calling process user id. You can use `id` command to find the uid of a particular user. -``` +```sh $ trace.py \ 'p::SyS_chown "file = %s, to_uid = %d, to_gid = %d, from_uid = %d", arg1, arg2, arg3, $uid' \ 'p::SyS_fchown "fd = %d, to_uid = %d, to_gid = %d, from_uid = %d", arg1, arg2, arg3, $uid' \ @@ -338,17 +338,17 @@ PID TID COMM FUNC - ##### Example 2 Suppose you want to count nonvoluntary context switches (`nvcsw`) in your bpf based performance monitoring tools and you do not know what is the proper method. `/proc//status` already tells you the number (`nonvoluntary_ctxt_switches`) for a pid and you can use `trace.py` to do a quick experiment to verify your method. With kernel source code, the `nvcsw` is counted at file `linux/kernel/sched/core.c` function `__schedule` and under condition -``` +```c !(!preempt && prev->state) // i.e., preempt || !prev->state ``` The `__schedule` function is marked as `notrace`, and the best place to evaluate the above condition seems in `sched/sched_switch` tracepoint called inside function `__schedule` and defined in `linux/include/trace/events/sched.h`. `trace.py` already has `args` being the pointer to the tracepoint `TP_STRUCT__entry`. The above condition in function `__schedule` can be represented as -``` +```c args->prev_state == TASK_STATE_MAX || args->prev_state == 0 ``` The below command can be used to count the involuntary context switches (per process or per pid) and compare to `/proc//status` or `/proc//task//status` for correctness, as in typical cases, involuntary context switches are not very common. -``` +```sh $ trace.py -p 1134138 't:sched:sched_switch (args->prev_state == TASK_STATE_MAX || args->prev_state == 0)' PID TID COMM FUNC 1134138 1134140 contention_test sched_switch @@ -365,7 +365,7 @@ PID TID COMM FUNC This example is related to issue [1231](https://github.com/iovisor/bcc/issues/1231) and [1516](https://github.com/iovisor/bcc/issues/1516) where uprobe does not work at all in certain cases. First, you can do a `strace` as below -``` +```sh $ strace trace.py 'r:bash:readline "%s", retval' ... perf_event_open(0x7ffd968212f0, -1, 0, -1, 0x8 /* PERF_FLAG_??? */) = -1 EIO (Input/output error) @@ -373,23 +373,23 @@ perf_event_open(0x7ffd968212f0, -1, 0, -1, 0x8 /* PERF_FLAG_??? */) = -1 EIO (In ``` The `perf_event_open` syscall returns `-EIO`. Digging into kernel uprobe related codes in `/kernel/trace` and `/kernel/events` directories to search `EIO`, the function `uprobe_register` is the most suspicious. Let us find whether this function is called or not and what is the return value if it is called. In one terminal using the following command to print out the return value of uprobe_register, -``` +```sh $ trace.py 'r::uprobe_register "ret = %d", retval' ``` In another terminal run the same bash uretprobe tracing example, and you should get -``` +```sh $ trace.py 'r::uprobe_register "ret = %d", retval' PID TID COMM FUNC - 1041401 1041401 python2.7 uprobe_register ret = -5 ``` The `-5` error code is EIO. This confirms that the following code in function `uprobe_register` is the most suspicious culprit. -``` +```c if (!inode->i_mapping->a_ops->readpage && !shmem_mapping(inode->i_mapping)) return -EIO; ``` The `shmem_mapping` function is defined as -``` +```c bool shmem_mapping(struct address_space *mapping) { return mapping->a_ops == &shmem_aops; @@ -397,7 +397,7 @@ bool shmem_mapping(struct address_space *mapping) ``` To confirm the theory, find what is `inode->i_mapping->a_ops` with the following command -``` +```sh $ trace.py -I 'linux/fs.h' 'p::uprobe_register(struct inode *inode) "a_ops = %llx", inode->i_mapping->a_ops' PID TID COMM FUNC - 814288 814288 python2.7 uprobe_register a_ops = ffffffff81a2adc0 diff --git a/bcc-documents/tutorial_bcc_python_developer.md b/src/bcc-documents/tutorial_bcc_python_developer.md similarity index 99% rename from bcc-documents/tutorial_bcc_python_developer.md rename to src/bcc-documents/tutorial_bcc_python_developer.md index c56864e..7a401c2 100644 --- a/bcc-documents/tutorial_bcc_python_developer.md +++ b/src/bcc-documents/tutorial_bcc_python_developer.md @@ -12,7 +12,7 @@ This observability tutorial contains 17 lessons, and 46 enumerated things to lea Start by running [examples/hello_world.py](https://github.com/iovisor/bcc/tree/master/examples/hello_world.py), while running some commands (eg, "ls") in another session. It should print "Hello, World!" for new processes. If not, start by fixing bcc: see [INSTALL.md](https://github.com/iovisor/bcc/tree/master/INSTALL.md). -``` +```sh # ./examples/hello_world.py bash-13364 [002] d... 24573433.052937: : Hello, World! bash-13364 [003] d... 24573436.642808: : Hello, World! @@ -50,8 +50,8 @@ Improve it by printing "Tracing sys_sync()... Ctrl-C to end." when the program f This program is in [examples/tracing/hello_fields.py](https://github.com/iovisor/bcc/tree/master/examples/tracing/hello_fields.py). Sample output (run commands in another session): -``` -# ./examples/tracing/hello_fields.py +```sh +# examples/tracing/hello_fields.py TIME(s) COMM PID MESSAGE 24585001.174885999 sshd 1432 Hello, World! 24585001.195710000 sshd 15780 Hello, World! @@ -104,8 +104,8 @@ Remember the days of sysadmins typing ```sync``` three times on a slow console b The following example times how quickly the ```do_sync``` function is called, and prints output if it has been called more recently than one second ago. A ```sync;sync;sync``` will print output for the 2nd and 3rd sync's: -``` -# ./examples/tracing/sync_timing.py +```sh +# examples/tracing/sync_timing.py Tracing for quick sync's... Ctrl-C to end At time 0.00 s: multiple syncs detected, last 95 ms ago At time 0.10 s: multiple syncs detected, last 96 ms ago @@ -175,8 +175,8 @@ Modify the sync_timing.py program (prior lesson) to store the count of all kerne Browse the [examples/tracing/disksnoop.py](https://github.com/iovisor/bcc/tree/master/examples/tracing/disksnoop.py) program to see what is new. Here is some sample output: -``` -# ./disksnoop.py +```sh +# disksnoop.py TIME(s) T BYTES LAT(ms) 16458043.436012 W 4096 3.13 16458043.437326 W 4096 4.44 @@ -240,8 +240,8 @@ This is a pretty interesting program, and if you can understand all the code, yo Let's finally stop using bpf_trace_printk() and use the proper BPF_PERF_OUTPUT() interface. This will also mean we stop getting the free trace_field() members like PID and timestamp, and will need to fetch them directly. Sample output while commands are run in another session: -``` -# ./hello_perf_output.py +```sh +# hello_perf_output.py TIME(s) COMM PID MESSAGE 0.000000000 bash 22986 Hello, perf_output! 0.021080275 systemd-udevd 484 Hello, perf_output! @@ -325,8 +325,8 @@ Rewrite sync_timing.py, from a prior lesson, to use ```BPF_PERF_OUTPUT```. The following tool records a histogram of disk I/O sizes. Sample output: -``` -# ./bitehist.py +```sh +# bitehist.py Tracing... Hit Ctrl-C to end. ^C kbytes : count distribution @@ -395,8 +395,8 @@ Write a program that times disk I/O, and prints a histogram of their latency. Di This example is split into separate Python and C files. Example output: -``` -# ./vfsreadlat.py 1 +```sh +# vfsreadlat.py 1 Tracing... Hit Ctrl-C to end. usecs : count distribution 0 -> 1 : 0 | | @@ -443,8 +443,8 @@ Browse the code in [examples/tracing/vfsreadlat.py](https://github.com/iovisor/b Tracing while a ```dd if=/dev/urandom of=/dev/null bs=8k count=5``` is run: -``` -# ./urandomread.py +```sh +# urandomread.py TIME(s) COMM PID GOTBITS 24652832.956994001 smtp 24690 384 24652837.726500999 dd 24692 65536 @@ -486,7 +486,7 @@ Things to learn: 1. ```TRACEPOINT_PROBE(random, urandom_read)```: Instrument the kernel tracepoint ```random:urandom_read```. These have a stable API, and thus are recommend to use instead of kprobes, wherever possible. You can run ```perf list``` for a list of tracepoints. Linux >= 4.7 is required to attach BPF programs to tracepoints. 1. ```args->got_bits```: ```args``` is auto-populated to be a structure of the tracepoint arguments. The comment above says where you can see that structure. Eg: -``` +```sh # cat /sys/kernel/debug/tracing/events/random/urandom_read/format name: urandom_read ID: 972 @@ -513,8 +513,8 @@ Convert disksnoop.py from a previous lesson to use the ```block:block_rq_issue`` This program instruments a user-level function, the ```strlen()``` library function, and frequency counts its string argument. Example output: -``` -# ./strlen_count.py +```sh +# strlen_count.py Tracing strlen()... Hit Ctrl-C to end. ^C COUNT STRING 1 " " @@ -596,8 +596,8 @@ Things to learn: This program instruments a user statically-defined tracing (USDT) probe, which is the user-level version of a kernel tracepoint. Sample output: -``` -# ./nodejs_http_server.py 24728 +```sh +# nodejs_http_server.py 24728 TIME(s) COMM PID ARGS 24653324.561322998 node 24728 path:/index.html 24653335.343401998 node 24728 path:/images/welcome.png