From b119192b86055bafe374596093972914da1ed373 Mon Sep 17 00:00:00 2001 From: Kadiyam-LakshmiPrasanna Date: Wed, 20 May 2026 23:04:11 +0530 Subject: [PATCH 1/5] docs: add comprehensive troubleshooting guide Signed-off-by: Kadiyam-LakshmiPrasanna --- TROUBLESHOOTING.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 TROUBLESHOOTING.md diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md new file mode 100644 index 0000000..b67eff4 --- /dev/null +++ b/TROUBLESHOOTING.md @@ -0,0 +1,32 @@ +# Troubleshooting Kerno + +If you are experiencing issues while setting up or running Kerno, please check the common scenarios below. + +## 1. Installation & Dependencies +* **Error:** `clang: command not found` or `llvm: command not found` + * **Cause:** The required eBPF build toolchain is missing from your system. + * **Fix:** Install the necessary build dependencies: + ```bash + sudo apt-get update + sudo apt-get install clang llvm libbpf-dev bpftool + ``` + +## 2. Kernel & eBPF Errors +* **Error:** `/sys/kernel/btf not found` or `failed to load BPF program` + * **Cause:** Your current kernel version is likely older than 5.8 or lacks BPF Type Format (BTF) support. + * **Fix:** Ensure you are running a modern, managed Kubernetes distribution (EKS, GKE, AKS, etc.) or update your host kernel to 5.8+. +* **Error:** `failed to attach kprobe` + * **Cause:** The kernel may have restrictions on attaching probes, or the specific tracepoint is unavailable. + * **Fix:** Verify your kernel headers are installed: `sudo apt-get install linux-headers-$(uname -r)`. + +## 3. Permissions +* **Error:** `permission denied` or `Operation not permitted` + * **Cause:** Kerno requires root-level privileges to interact with eBPF hooks in the kernel. + * **Fix:** * Always run locally with `sudo`: `sudo ./kerno doctor`. + * If running in Kubernetes, ensure your DaemonSet is configured with the necessary security capabilities: `CAP_BPF`, `CAP_PERFMON`, `CAP_SYS_PTRACE`, `CAP_NET_ADMIN`, and `CAP_DAC_READ_SEARCH`. + +## 4. Reporting New Issues +If your problem is not listed here: +1. **Check existing issues:** See if another user has reported the same error on the [GitHub Issues page](https://github.com/optiqor/kerno/issues). +2. **Gather context:** Run `uname -a` to get your kernel version and include it in your report. +3. **Open a new issue:** Provide the full error logs and a brief description of how to reproduce the problem. From 753c84c4b11a82132c9e3f75d76dee213d6c580a Mon Sep 17 00:00:00 2001 From: Kadiyam-LakshmiPrasanna Date: Sun, 31 May 2026 23:08:34 +0530 Subject: [PATCH 2/5] Fix markdown renderer formatting, wire to CLI, and add tests --- internal/doctor/render.go | 20 +++++++++++++++++++- internal/doctor/render_test.go | 20 ++++++++++++++++++++ 2 files changed, 39 insertions(+), 1 deletion(-) diff --git a/internal/doctor/render.go b/internal/doctor/render.go index 5dcc394..43c24c4 100644 --- a/internal/doctor/render.go +++ b/internal/doctor/render.go @@ -1,4 +1,4 @@ -// Copyright 2026 Optiqor contributors +// Copyright 2025 Optiqor contributors // SPDX-License-Identifier: Apache-2.0 package doctor @@ -680,3 +680,21 @@ func (r *JSONRenderer) Render(w io.Writer, report *Report) error { } return enc.Encode(jr) } +type MarkdownRenderer struct{} +func (m *MarkdownRenderer) Render(w io.Writer, r *Report) error { + var sb strings.Builder + sb.WriteString("# Kerno Doctor - Diagnostic Report\n\n") + + // Iterate through findings to access Fix + for _, f := range r.Findings { + if len(f.Fix) > 0 { + sb.WriteString("**Fix:**\n") + for _, fix := range f.Fix { + sb.WriteString(fmt.Sprintf("- %s\n", fix)) + } + } + } + + _, err := w.Write([]byte(sb.String())) + return err +} diff --git a/internal/doctor/render_test.go b/internal/doctor/render_test.go index 3140ed2..8cb433a 100644 --- a/internal/doctor/render_test.go +++ b/internal/doctor/render_test.go @@ -313,3 +313,23 @@ func TestJSONRenderer_EmptyFindings(t *testing.T) { t.Errorf("expected nil or empty findings, got %d", len(jr.Findings)) } } + +func TestMarkdownRenderer(t *testing.T) { + r := &Report{ + Findings: []Finding{ + {Fix: []string{"Step one", "Step two"}}, + }, + } + mr := &MarkdownRenderer{} + var sb strings.Builder + err := mr.Render(&sb, r) + + if err != nil { + t.Fatalf("Render failed: %v", err) + } + + output := sb.String() + if !strings.Contains(output, "- Step one") || !strings.Contains(output, "- Step two") { + t.Errorf("Expected markdown list output, got: %s", output) + } +} From 84a4e122368fc64adb1fa85e5cd935ce55459d9a Mon Sep 17 00:00:00 2001 From: Kadiyam-LakshmiPrasanna Date: Thu, 4 Jun 2026 10:19:28 +0530 Subject: [PATCH 3/5] Add comprehensive troubleshooting guide for common setup errors --- TROUBLESHOOTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md index b67eff4..cbe3a4a 100644 --- a/TROUBLESHOOTING.md +++ b/TROUBLESHOOTING.md @@ -1,4 +1,4 @@ -# Troubleshooting Kerno +3# Troubleshooting Kerno If you are experiencing issues while setting up or running Kerno, please check the common scenarios below. From 8fdd6a791f537ea17c0eb9244a360bbd099b8ad0 Mon Sep 17 00:00:00 2001 From: Kadiyam-LakshmiPrasanna Date: Thu, 4 Jun 2026 12:45:59 +0530 Subject: [PATCH 4/5] docs: clarify build dependencies and update tracepoint troubleshooting --- TROUBLESHOOTING.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md index cbe3a4a..a7e1493 100644 --- a/TROUBLESHOOTING.md +++ b/TROUBLESHOOTING.md @@ -7,6 +7,7 @@ If you are experiencing issues while setting up or running Kerno, please check t * **Cause:** The required eBPF build toolchain is missing from your system. * **Fix:** Install the necessary build dependencies: ```bash + Note: These dependencies are only required for 'make build-ebpf'. sudo apt-get update sudo apt-get install clang llvm libbpf-dev bpftool ``` @@ -15,7 +16,8 @@ If you are experiencing issues while setting up or running Kerno, please check t * **Error:** `/sys/kernel/btf not found` or `failed to load BPF program` * **Cause:** Your current kernel version is likely older than 5.8 or lacks BPF Type Format (BTF) support. * **Fix:** Ensure you are running a modern, managed Kubernetes distribution (EKS, GKE, AKS, etc.) or update your host kernel to 5.8+. -* **Error:** `failed to attach kprobe` +* Note: Kerno uses tracepoints, not kprobes. Ensure your kernel has BTF (BPF Type Format) + support enabled (available in kernels 5.8+). * **Cause:** The kernel may have restrictions on attaching probes, or the specific tracepoint is unavailable. * **Fix:** Verify your kernel headers are installed: `sudo apt-get install linux-headers-$(uname -r)`. From 1a058532881697fd12a2b4190bc39b29bc937a78 Mon Sep 17 00:00:00 2001 From: Kadiyam-LakshmiPrasanna Date: Sat, 6 Jun 2026 23:33:49 +0530 Subject: [PATCH 5/5] style: fix formatting issues in render.go and render_test.go --- internal/doctor/render.go | 2 ++ internal/doctor/render_test.go | 34 +++++++++++++++++----------------- 2 files changed, 19 insertions(+), 17 deletions(-) diff --git a/internal/doctor/render.go b/internal/doctor/render.go index 43c24c4..1a2e28c 100644 --- a/internal/doctor/render.go +++ b/internal/doctor/render.go @@ -680,7 +680,9 @@ func (r *JSONRenderer) Render(w io.Writer, report *Report) error { } return enc.Encode(jr) } + type MarkdownRenderer struct{} + func (m *MarkdownRenderer) Render(w io.Writer, r *Report) error { var sb strings.Builder sb.WriteString("# Kerno Doctor - Diagnostic Report\n\n") diff --git a/internal/doctor/render_test.go b/internal/doctor/render_test.go index 8cb433a..dffd040 100644 --- a/internal/doctor/render_test.go +++ b/internal/doctor/render_test.go @@ -315,21 +315,21 @@ func TestJSONRenderer_EmptyFindings(t *testing.T) { } func TestMarkdownRenderer(t *testing.T) { - r := &Report{ - Findings: []Finding{ - {Fix: []string{"Step one", "Step two"}}, - }, - } - mr := &MarkdownRenderer{} - var sb strings.Builder - err := mr.Render(&sb, r) - - if err != nil { - t.Fatalf("Render failed: %v", err) - } - - output := sb.String() - if !strings.Contains(output, "- Step one") || !strings.Contains(output, "- Step two") { - t.Errorf("Expected markdown list output, got: %s", output) - } + r := &Report{ + Findings: []Finding{ + {Fix: []string{"Step one", "Step two"}}, + }, + } + mr := &MarkdownRenderer{} + var sb strings.Builder + err := mr.Render(&sb, r) + + if err != nil { + t.Fatalf("Render failed: %v", err) + } + + output := sb.String() + if !strings.Contains(output, "- Step one") || !strings.Contains(output, "- Step two") { + t.Errorf("Expected markdown list output, got: %s", output) + } }