Fixed illustration

.env

@@ -1,4 +1,3 @@
-# Socat Proxy Configuration
 TARGET_HOST= # Target hostname/IP to proxy to
 TARGET_PORT= # Target port to proxy to
 UNIX_SOCKET_NAME= # Name of the socket file

README.MD

@@ -2,15 +2,43 @@
 
 A lightweight Docker container that creates a UNIX socket proxy to TCP connections using socat and Alpine Linux.
 
+> [!NOTE]
+>_Github repo is a mirror of https://git.djeex.fr/Djeex/socat-proxy. You'll find full package, history and release note there._
+
+## 📑 Table of Contents
+
+- [🚀 Features](#-features)
+- [🔧 How It Works](#-how-it-works)
+- [📋 Use Case](#-use-case)
+- [🛠️ Configuration](#️-configuration)
+  - [Environment Variables](#environment-variables)
+- [🚢 Quick Start](#-quick-start)
+  - [Using Docker Compose (Recommended)](#using-docker-compose-recommended)
+  - [Using Docker Run](#using-docker-run)
+- [💡 Deployment example for Beszel](#-example-secure-docker-socket-access-for-host-mode-containers)
+
 ## 🚀 Features
 
 - **Configurable**: Environment variable driven configuration
 - **Socket Management**: Automatic UNIX socket creation and cleanup
 - **Production Ready**: Includes proper error handling and logging
 
-## 📋 Use Cases example
+## 🔧 How It Works
 
-- Proxy Docker socket from a docker proxy to a container in host mode
+1. **Socket Check**: Verifies if UNIX socket exists at startup
+2. **Cleanup**: Removes existing socket file/folder if present
+3. **Socket Creation**: Creates new UNIX socket using `nc -lU`
+4. **Proxy Start**: Starts socat to proxy UNIX socket to TCP endpoint
+
+## 📋 Use Case
+
+Proxy Docker socket from a docker proxy to a container in host mode without directly exposing socket to host. For example:
+
+[Beszel](https://beszel.dev/) is a monitoring tool that requires `network_mode: host` to function properly. This creates a security challenge: Beszel needs access to the Docker socket, but it cannot reach a containerized docker-socket-proxy due to the network isolation. Running docker-socket-proxy in host mode or exposing port to host would also be highly insecure.
+
+**Socat-proxy solves this problem** by creating a secure bridge between host-mode containers and containerized socket proxies. It exposes a UNIX socket file on the host filesystem that Beszel can access, while securely forwarding all Docker API requests to the socket-proxy running on the bridge network.
+
+![](https://git.djeex.fr/Djeex/socat-proxy/raw/branch/main/illustration/socat-proxy.svg)
 
 ## 🛠️ Configuration
 
@@ -23,50 +51,106 @@ A lightweight Docker container that creates a UNIX socket proxy to TCP connectio
 | `UNIX_SOCKET_NAME` | - | Name of the socket file | `docker.sock` |
 | `UNIX_SOCKET_PATH` | - | Path to UNIX socket inside container | `/socket` |
 | `HOST_SOCKET_PATH` | - | Host path for socket mounting | `/docker/beszel-agent/sock` |
+| `DEBUG_LEVEL` | - | Level of logs verbose | `0`,`1`,`2`,`3`  |
 
 ## 🚢 Quick Start
 
 ### Using Docker Compose (Recommended)
 
-1. Clone the repository:
+1. Create a `.env` file with your configuration:
 ```bash
-git clone https://git.djeex.fr/Djeex/socat-proxy
-cd socat-proxy
+TARGET_HOST= #your target host
+TARGET_PORT= #your target host port
+UNIX_SOCKET_NAME= #your socket file name
+UNIX_SOCKET_PATH= #your socket folder path inside socat-proxy
+HOST_SOCKET_PATH= #your socket folder path inside your host
+DEBUG_LEVEL=1
 ```
 
-2. Configure environment variables in `.env` file:
-```bash
-TARGET_HOST= # Target hostname/IP to proxy to
-TARGET_PORT= # Target port to proxy to
-UNIX_SOCKET_NAME= # Name of the socket file
-UNIX_SOCKET_PATH= # Path to UNIX socket inside container
-HOST_SOCKET_PATH= # Host path for socket mounting
+2. Create a `compose.yml` file:
+```yaml
+services:
+  socat-proxy:
+    image: git.djeex.fr/djeex/socat-proxy:latest
+    environment:
+      - TARGET_HOST=${TARGET_HOST}
+      - TARGET_PORT=${TARGET_PORT}
+      - UNIX_SOCKET_NAME=${UNIX_SOCKET_NAME}
+      - UNIX_SOCKET_PATH=${UNIX_SOCKET_PATH}
+      - HOST_SOCKET_PATH=${HOST_SOCKET_PATH}
+      - DEBUG_LEVEL=${DEBUG_LEVEL}
+    volumes:
+      - ${HOST_SOCKET_PATH}:${UNIX_SOCKET_PATH}
+    restart: unless-stopped
 ```
 
 3. Start the service:
 ```bash
-docker-compose up -d
+docker compose up -d
 ```
 
 ### Using Docker Run
 
 ```bash
-docker build -t socat-proxy .
-
 docker run -d \
   --name socat-proxy \
-  -e TARGET_HOST=your-target-host \
-  -e TARGET_PORT=your-target-port \
-  -e UNIX_SOCKET_NAME=your-socket-name \
-  -e UNIX_SOCKET_PATH=your-unix-socket-path \
-  -e HOST_SOCKET_PATH=your-socket-host-path \
-  -v /your-origin-socket-path:/socket \
-  socat-proxy
+  -e TARGET_HOST= #your target host \
+  -e TARGET_PORT= #your target host port \
+  -e UNIX_SOCKET_NAME= #your socket file name \
+  -e UNIX_SOCKET_PATH= #your socket folder path inside socat-proxy \
+  -e HOST_SOCKET_PATH= #your socket folder path inside your host\
+  -e DEBUG_LEVEL=1 \
+  -v ${HOST_SOCKET_PATH}:${UNIX_SOCKET_PATH}$ \
+  git.djeex.fr/djeex/socat-proxy:latest
 ```
 
-## 🔧 How It Works
 
-1. **Socket Check**: Verifies if UNIX socket exists at startup
-2. **Cleanup**: Removes existing socket file/folder if present
-3. **Socket Creation**: Creates new UNIX socket using `nc -lU`
-4. **Proxy Start**: Starts socat to proxy UNIX socket to TCP endpoint
+## 💡 Deployment example for Beszel
+
+```yaml
+services:
+  socat-proxy:
+    image: git.djeex.fr/djeex/socat-proxy:latest
+    container_name: socat-proxy-beszel
+    environment:
+      - TARGET_HOST=${TARGET_HOST}
+      - TARGET_PORT=${TARGET_PORT}
+      - UNIX_SOCKET_PATH=${UNIX_SOCKET_PATH}
+      - HOST_SOCKET_PATH=${HOST_SOCKET_PATH}
+      - UNIX_SOCKET_NAME=${UNIX_SOCKET_NAME}
+    volumes:
+      - ${HOST_SOCKET_PATH}:${UNIX_SOCKET_PATH}
+    restart: unless-stopped
+    depends_on:
+      - ${TARGET_HOST}
+
+  socket-proxy:
+    image: lscr.io/linuxserver/socket-proxy:latest
+    container_name: ${TARGET_HOST}
+    security_opt:
+      - no-new-privileges:true
+    environment:
+      - CONTAINERS=1
+      - INFO=1
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    restart: unless-stopped
+    read_only: true
+    tmpfs:
+      - /run
+
+  beszel-agent:
+    image: henrygd/beszel-agent:latest
+    container_name: beszel-agent
+    restart: unless-stopped
+    network_mode: host
+    security_opt:
+      - no-new-privileges:true
+    volumes:
+      - ${HOST_SOCKET_PATH}/${UNIX_SOCKET_NAME}:/var/run/docker.sock:ro
+    environment:
+      - #... your Beszel environment var 
+    depends_on:
+      - socat-proxy
+```
+

VERSION

@@ -1 +1 @@
-1.0
+1.0.0

entrypoint.sh

@@ -4,13 +4,7 @@ set -e
 CYAN="\033[1;36m"
 NC="\033[0m"
 
-TARGET_HOST=${TARGET_HOST}
-TARGET_PORT=${TARGET_PORT}
-UNIX_SOCKET_NAME=${UNIX_SOCKET_NAME}
-UNIX_SOCKET_PATH=${UNIX_SOCKET_PATH}
-HOST_SOCKET_PATH=${HOST_SOCKET_PATH}
-
-# Remove trailing slashes to avoid double slashes
+DEBUG_LEVEL=${DEBUG_LEVEL:-1}
 UNIX_SOCKET_PATH=${UNIX_SOCKET_PATH%/}
 HOST_SOCKET_PATH=${HOST_SOCKET_PATH%/}
 
@@ -20,7 +14,7 @@ FULL_UNIX_SOCKET_PATH="$UNIX_SOCKET_PATH/$UNIX_SOCKET_NAME"
 VERSION=$(cat VERSION)
 
 echo -e "${CYAN}╭────────────────────────────────────────────────╮${NC}"
-echo -e "${CYAN}│${NC}         Socat-proxy - Version ${VERSION}${NC}            ${CYAN}│${NC}"
+echo -e "${CYAN}│${NC}            Socat-proxy - Version ${VERSION}${NC}         ${CYAN}│${NC}"
 echo -e "${CYAN}├────────────────────────────────────────────────┤${NC}"
 echo -e "${CYAN}│${NC} Source: https://git.djeex.fr/Djeex/socat-proxy ${CYAN}│${NC}"
 echo -e "${CYAN}│${NC} Mirror: https://github.com/Djeex/socat-proxy   ${CYAN}│${NC}"
@@ -70,7 +64,7 @@ if [ -e "$FULL_UNIX_SOCKET_PATH" ]; then
     fi
 fi
 
-echo [~] Creating socket directory structure...
+echo "[~] Creating socket directory structure..."
 # Create directory if needed
 if mkdir -p "$UNIX_SOCKET_PATH"; then
     echo "[✓] Created directory $UNIX_SOCKET_PATH"
@@ -80,11 +74,18 @@ else
 fi
 
 echo "[~] Creating socket with netcat..."
-# Create socket with nc -lU in background and then kill it to create the socket file
-if timeout 1 nc -lU "$FULL_UNIX_SOCKET_PATH" 2>/dev/null || true; then
-    echo "[✓] Socket created at $FULL_UNIX_SOCKET_PATH"
+# Create socket file by touching it, then remove it (this creates the path but leaves it clean for socat)
+touch "$FULL_UNIX_SOCKET_PATH"
+rm "$FULL_UNIX_SOCKET_PATH"
+echo "[✓] Socket path prepared at $FULL_UNIX_SOCKET_PATH"
+
+# Debug: Check if socket file exists and its permissions
+if [ -S "$FULL_UNIX_SOCKET_PATH" ]; then
+    echo "[✓] Socket file exists and is a socket"
+    ls -la "$FULL_UNIX_SOCKET_PATH"
 else
-    echo "[!] Socket creation with netcat had issues, but continuing..."
+    echo "[!] Socket file does not exist or is not a socket"
+    ls -la "$UNIX_SOCKET_PATH"
 fi
 
 echo "[~] Testing connection to target..."
@@ -111,11 +112,32 @@ cleanup() {
 trap cleanup SIGTERM SIGINT
 
 echo "[~] Starting socat proxy..."
-# Start socat with verbose logging and redirect to stdout/stderr
-if socat -d -d UNIX-LISTEN:$FULL_UNIX_SOCKET_PATH,fork,unlink-early TCP:$TARGET_HOST:$TARGET_PORT & then
+# Start socat with configurable verbosity
+DEBUG_FLAGS=""
+if [ "$DEBUG_LEVEL" -eq 1 ]; then
+    DEBUG_FLAGS="-d"
+elif [ "$DEBUG_LEVEL" -eq 2 ]; then
+    DEBUG_FLAGS="-d -d"
+elif [ "$DEBUG_LEVEL" -eq 3 ]; then
+    DEBUG_FLAGS="-d -d -d"
+fi
+
+echo "[i] Using debug level: $DEBUG_LEVEL ($DEBUG_FLAGS)"
+
+if socat $DEBUG_FLAGS UNIX-LISTEN:$FULL_UNIX_SOCKET_PATH,fork,unlink-early TCP:$TARGET_HOST:$TARGET_PORT & then
     SOCAT_PID=$!
     echo "[✓] Socat started with PID: $SOCAT_PID"
+    echo "[i] Socat command: socat -d -d UNIX-LISTEN:$FULL_UNIX_SOCKET_PATH,fork,unlink-early TCP:$TARGET_HOST:$TARGET_PORT"
     echo "[~] Container is ready and running..."
+    
+    # Debug: Check socket after socat starts
+    sleep 2
+    if [ -S "$FULL_UNIX_SOCKET_PATH" ]; then
+        echo "[✓] Socat socket is active"
+        ls -la "$FULL_UNIX_SOCKET_PATH"
+    else
+        echo "[!] Socat socket not found"
+    fi
 else
     echo "[✗] Failed to start socat proxy"
     exit 1
@@ -127,5 +149,4 @@ while kill -0 "$SOCAT_PID" 2>/dev/null; do
 done
 
 echo "[✗] Socat process has stopped"
-exit 1
-
+exit 1