From 4da510dff13377e751f0f9da09e1525443ae4d11 Mon Sep 17 00:00:00 2001
From: Graham McIntire <graham@mcintire.me>
Date: Tue, 10 Feb 2026 13:22:37 -0600
Subject: [PATCH] Add NET_RAW capability requirement for ICMP ping

Agent was crashing with segmentation fault (exit code 139) when
attempting ICMP ping health checks. The surge-ping library requires
CAP_NET_RAW capability to create raw sockets for ICMP.

Changes:
- Added cap_add: NET_RAW to docker-compose.example.yml
- Updated README docker-compose example
- Added troubleshooting section for exit code 139 crashes

Without this capability, the agent crashes immediately after
successful ping execution when the surge-ping library attempts
to clean up raw socket resources.
---
 README.md                  | 14 ++++++++++++++
 docker-compose.example.yml |  4 ++++
 2 files changed, 18 insertions(+)

diff --git a/README.md b/README.md
index 218c7e8..5a80da0 100644
--- a/README.md
+++ b/README.md
@@ -38,6 +38,9 @@ services:
   towerops-agent:
     image: ghcr.io/towerops-app/towerops-agent:latest
     restart: unless-stopped
+    # Required for ICMP ping health checks
+    cap_add:
+      - NET_RAW
     environment:
       - TOWEROPS_API_URL=https://towerops.net
       - TOWEROPS_AGENT_TOKEN=your-agent-token-here
@@ -122,6 +125,17 @@ docker build -t towerops-agent .
 
 ## Troubleshooting
 
+### Agent Crashes with Segmentation Fault (Exit Code 139)
+
+This typically occurs when the container doesn't have the `NET_RAW` capability required for ICMP ping:
+
+```yaml
+cap_add:
+  - NET_RAW
+```
+
+Add this to your `docker-compose.yml` under the agent service. Without this capability, the agent will crash when attempting health checks.
+
 ### Agent Not Connecting
 
 - Verify the API URL is correct (accepts http://, https://, ws://, or wss://)
diff --git a/docker-compose.example.yml b/docker-compose.example.yml
index 689d630..08d5d0a 100644
--- a/docker-compose.example.yml
+++ b/docker-compose.example.yml
@@ -4,6 +4,10 @@ services:
     container_name: towerops-agent
     restart: unless-stopped
 
+    # Required for ICMP ping health checks
+    cap_add:
+      - NET_RAW
+
     environment:
       # Required: Agent authentication token (from Towerops web UI)
       # Get this from: Organization > Agents > Create New Agent