From 0010a50caf4d27de409056ac86dd2dd0608526e7 Mon Sep 17 00:00:00 2001 From: AugustasV Date: Sun, 28 Nov 2021 21:46:36 +0100 Subject: [PATCH 1/4] Update README.md --- README.md | 26 +++++++++----------------- 1 file changed, 9 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 20566cf..7495d86 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,9 @@ NetTracer is a tool for tracing TCP events and collecting network connections me The BPF program, composed of BPF maps and kprobes, is compiled to an ELF object file. At runtime, that object file is loaded by NetTracer using utilities found in _bpf\_generic_. -NetTracer does not have any runtime dependencies on kernel headers, nor it is tied to any specific kernel version or configuration. To adapt to the currently running kernel at runtime, NetTracer creates a series of TCP connections with known parameters (such as known IP addresses and ports) and discovers where those parameters are stored in the kernel struct sock. This process is often referred to as offset guessing. Since a BPF programs cannot loop, NetTracer does not directly iterate over the possible offsets. It is instead controlled from user space by the binary using a state machine. +# How NetTracer works + +NetTracer does not have any runtime dependencies on kernel headers, nor it is tied to any specific kernel version or configuration. To adapt to the currently running kernel at runtime, NetTracer creates a series of TCP connections with known parameters (such as known IP addresses and ports) and discovers where those parameters are stored in the kernel [struct sock](https://www.kernel.org/doc/htmldocs/networking/API-struct-sock.html). This process is often referred to as offset guessing. Since a BPF programs cannot loop, NetTracer does not directly iterate over the possible offsets. It is instead controlled from user space by the binary using a state machine. Only Linux kernels of version 4.15 or above are supported. NetTracer was inspired by [weaveworks' tcptracer-bpf](https://github.com/weaveworks/tcptracer-bpf). @@ -53,16 +55,6 @@ make test-project You may want to see the _Dockerfile_ to check what dependencies need to be installed. -Building with conan and cmake: - -``` -mkdir build && cd build -conan install --build=boost .. -cmake -DCONAN_DEPS=1 -DCMAKE_BUILD_TYPE=Release -DLLVM_VERSION=10 .. -cmake --build . -ctest . -``` - ## Usage To run NetTracer, simply do this: @@ -75,12 +67,12 @@ This way, NetTracer's going to start in logging mode - all the information about Note that you need the following capabilities in order to run NetTracer: -- _CAP\_DAC\_READ_SEARCH__ -- _CAP\_SYS\_PTRACE_ -- _CAP\_SYS\_RESOURCE_ - _CAP\_BPF_ +- _CAP\_DAC\_OVERRIDE_ - _CAP\_PERFMON_ -- _CAP\_SYS\_ADMIN_ (only if kernel version < 5.8, used instead of _CAP\_BPF_ and _CAP\_PERFMON_) +- _CAP\_SYS\_ADMIN_ +- _CAP\_SYS\_PTRACE_ +- _CAP\_SYS\_RESOURCE_ However, to obtain a cleaner output, more appropriate for e.g. collecting metrics from NetTracer by an external tool, you should add _-d_ option: @@ -121,8 +113,8 @@ SLAs apply according to the customer's support level. ## Contributing -See CONTRIBUTING.md for details on submitting changes. +See [CONTRIBUTING.md](./CONTRIBUTING.md) for details on how to submit changes and how to prepare [local development environment](./CONTRIBUTING.md#local-deployment-environment-setup-necessary-tools). ## License -NetTracer is under Apache 2.0 license. See LICENSE for details. +NetTracer is under Apache 2.0 license. See LICENSE for details. \ No newline at end of file From e9bb476734b4ee66e2d4942d6a5a05466d6acc1f Mon Sep 17 00:00:00 2001 From: AugustasV Date: Sun, 28 Nov 2021 21:51:16 +0100 Subject: [PATCH 2/4] devspace_github_actions --- .github/workflows/c-cpp.yml | 44 +++++++++++++++++++++++++++ .gitignore | 1 + CONTRIBUTING.md | 35 ++++++++++++++++++++-- devspace.yaml | 59 +++++++++++++++++++++++++++++++++++++ 4 files changed, 137 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/c-cpp.yml create mode 100644 devspace.yaml diff --git a/.github/workflows/c-cpp.yml b/.github/workflows/c-cpp.yml new file mode 100644 index 0000000..0d1d643 --- /dev/null +++ b/.github/workflows/c-cpp.yml @@ -0,0 +1,44 @@ +name: C/C++ CI + +on: + push: + branches: [ master ] + pull_request: + branches: [ master ] + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v2 + # - name: make + # run: make + push_to_registry: + name: Push Docker image to GitHub Packages + runs-on: ubuntu-latest + steps: + # required for buildx and multi platform build + - name: Set up QEMU + uses: docker/setup-qemu-action@v1 + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v1 + - name: Log in to Docker Hub + uses: docker/login-action@v1 + with: + username: ${{ secrets.CR_USERNAME }} + password: ${{ secrets.CR_PAT }} + - uses: actions/checkout@v2 + - name: Build container image + id: docker_build + uses: docker/build-push-action@v2 + with: + context: . + file: ./Dockerfile + push: true + platforms: linux/amd64,linux/arm64 + tags: | + ${{ secrets.CR_USERNAME }}/nettracer-bpf:latest + ${{ secrets.CR_USERNAME }}/nettracer-bpf:${{ github.run_number }} + - name: Image digest + run: echo ${{ steps.docker_build.outputs.digest }} diff --git a/.gitignore b/.gitignore index 428e38a..9ee0eb2 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,4 @@ build/ *.a *.so *.so.* +.devspace/ \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f97de73..a0698b0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,36 @@ -# NetTracer - ## How to Contribute You are welcome to contribute to NetTracer. Use issues for discussing proposals or to raise a question. If you have improvements to NetTracer, please submit your pull request. For those just getting started, consult this [guide](https://help.github.com/articles/creating-a-pull-request-from-a-fork/). + +## Local deployment environment setup necessary tools +* [Docker - One of containerization engines](https://docs.docker.com/engine/install/) +* [Minikube - local Kubernetes cluster](https://minikube.sigs.k8s.io/docs/start) +* [Kubectl - CLI tool for Kubernetes control](https://docs.docker.com/engine/install/) +* [DevSpace - Deploy & Develop Kubernetes Apps](https://devspace.sh/cli/docs/getting-started/installation/) +### Optional tools +* [Lens IDE - UI for kubectl commands](https://k8slens.dev) +## Quickstart + +After installation of Docker and Minikube + +``` +minikube start --driver=docker +``` + +Inside repo folder run command and select branch: + +``` +devspace dev +``` +It will take some time, project will be deployed into your local `minikube` cluster, and you will see deployment shell. +It's configured for a file sync between our Pods in k8s and your local project files. + +To remove created resource +``` +devspace purge +``` +To stop, delete minikube cluster +``` +minikube stop +minikube delete +``` \ No newline at end of file diff --git a/devspace.yaml b/devspace.yaml new file mode 100644 index 0000000..fb1433f --- /dev/null +++ b/devspace.yaml @@ -0,0 +1,59 @@ +version: v1beta11 + +vars: +- name: IMAGE + value: augustris/nettracer-bpf +- name: BRANCH + default: master + +deployments: +- name: nettracer-bpf + helm: + componentChart: true + + values: + containers: + - image: ${IMAGE} + +dev: + # `dev.sync` configures a file sync between our Pods in k8s and your local project files + sync: + - imageSelector: ${IMAGE} + excludePaths: + - .git/ + - .devspace/ + - .github/ + + terminal: + imageSelector: ${IMAGE} + command: + - /bin/bash + replacePods: + - imageSelector: ${IMAGE} + replaceImage: loftsh/alpine:latest + patches: + - op: replace + path: spec.containers[0].command + value: + - sleep + - op: replace + path: spec.containers[0].args + value: + - "9999999" + - op: remove + path: spec.containers[0].securityContext + +profiles: +- name: production + merge: + images: + app: + image: ${IMAGE} + dockerfile: ./Dockerfile + +dependencies: +- name: clone branch + source: + git: https://github.com/augustasv/nettracer-bpf + branch: ${BRANCH} + ignoreDependencies: true From 250c2c766c356dfdea7752e95fefc5a0ce6612a0 Mon Sep 17 00:00:00 2001 From: AugustasV Date: Sun, 28 Nov 2021 22:34:42 +0100 Subject: [PATCH 3/4] Update README.md --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a0698b0..e5915b4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,6 +9,7 @@ You are welcome to contribute to NetTracer. Use issues for discussing proposals * [DevSpace - Deploy & Develop Kubernetes Apps](https://devspace.sh/cli/docs/getting-started/installation/) ### Optional tools * [Lens IDE - UI for kubectl commands](https://k8slens.dev) + ## Quickstart After installation of Docker and Minikube From e72d18fcbde102cb445b635f06637c16f50961cf Mon Sep 17 00:00:00 2001 From: AugustasV Date: Sun, 5 Dec 2021 22:50:08 +0100 Subject: [PATCH 4/4] improvements --- .github/workflows/c-cpp.yml | 8 +++++--- README.md | 22 +++++++++++++++------- devspace.yaml | 2 +- 3 files changed, 21 insertions(+), 11 deletions(-) diff --git a/.github/workflows/c-cpp.yml b/.github/workflows/c-cpp.yml index 0d1d643..eb636ad 100644 --- a/.github/workflows/c-cpp.yml +++ b/.github/workflows/c-cpp.yml @@ -12,8 +12,6 @@ jobs: steps: - uses: actions/checkout@v2 - # - name: make - # run: make push_to_registry: name: Push Docker image to GitHub Packages runs-on: ubuntu-latest @@ -29,6 +27,10 @@ jobs: username: ${{ secrets.CR_USERNAME }} password: ${{ secrets.CR_PAT }} - uses: actions/checkout@v2 + - name: Set the value + id: version_env + run: | + echo cat {{ $GITHUB_WORKSPACE}}/version.properties >> $GITHUB_ENV - name: Build container image id: docker_build uses: docker/build-push-action@v2 @@ -39,6 +41,6 @@ jobs: platforms: linux/amd64,linux/arm64 tags: | ${{ secrets.CR_USERNAME }}/nettracer-bpf:latest - ${{ secrets.CR_USERNAME }}/nettracer-bpf:${{ github.run_number }} + ${{ secrets.CR_USERNAME }}/nettracer-bpf:${{ env.version }} - name: Image digest run: echo ${{ steps.docker_build.outputs.digest }} diff --git a/README.md b/README.md index 7495d86..c4cd009 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,7 @@ NetTracer is a tool for tracing TCP events and collecting network connections me The BPF program, composed of BPF maps and kprobes, is compiled to an ELF object file. At runtime, that object file is loaded by NetTracer using utilities found in _bpf\_generic_. -# How NetTracer works - -NetTracer does not have any runtime dependencies on kernel headers, nor it is tied to any specific kernel version or configuration. To adapt to the currently running kernel at runtime, NetTracer creates a series of TCP connections with known parameters (such as known IP addresses and ports) and discovers where those parameters are stored in the kernel [struct sock](https://www.kernel.org/doc/htmldocs/networking/API-struct-sock.html). This process is often referred to as offset guessing. Since a BPF programs cannot loop, NetTracer does not directly iterate over the possible offsets. It is instead controlled from user space by the binary using a state machine. +NetTracer does not have any runtime dependencies on kernel headers, nor it is tied to any specific kernel version or configuration. To adapt to the currently running kernel at runtime, NetTracer creates a series of TCP connections with known parameters (such as known IP addresses and ports) and discovers where those parameters are stored in the kernel struct sock. This process is often referred to as offset guessing. Since a BPF programs cannot loop, NetTracer does not directly iterate over the possible offsets. It is instead controlled from user space by the binary using a state machine. Only Linux kernels of version 4.15 or above are supported. NetTracer was inspired by [weaveworks' tcptracer-bpf](https://github.com/weaveworks/tcptracer-bpf). @@ -55,6 +53,16 @@ make test-project You may want to see the _Dockerfile_ to check what dependencies need to be installed. +Building with conan and cmake: + +``` +mkdir build && cd build +conan install --build=boost .. +cmake -DCONAN_DEPS=1 -DCMAKE_BUILD_TYPE=Release -DLLVM_VERSION=10 .. +cmake --build . +ctest . +``` + ## Usage To run NetTracer, simply do this: @@ -67,12 +75,12 @@ This way, NetTracer's going to start in logging mode - all the information about Note that you need the following capabilities in order to run NetTracer: -- _CAP\_BPF_ -- _CAP\_DAC\_OVERRIDE_ -- _CAP\_PERFMON_ -- _CAP\_SYS\_ADMIN_ +- _CAP\_DAC\_READ_SEARCH__ - _CAP\_SYS\_PTRACE_ - _CAP\_SYS\_RESOURCE_ +- _CAP\_BPF_ +- _CAP\_PERFMON_ +- _CAP\_SYS\_ADMIN_ (only if kernel version < 5.8, used instead of _CAP\_BPF_ and _CAP\_PERFMON_) However, to obtain a cleaner output, more appropriate for e.g. collecting metrics from NetTracer by an external tool, you should add _-d_ option: diff --git a/devspace.yaml b/devspace.yaml index fb1433f..d1a188e 100644 --- a/devspace.yaml +++ b/devspace.yaml @@ -54,6 +54,6 @@ profiles: dependencies: - name: clone branch source: - git: https://github.com/augustasv/nettracer-bpf + git: https://github.com/dynatrace-oss/nettracer-bpf branch: ${BRANCH} ignoreDependencies: true