Skip to content

index.md

Latest commit

 

History

History
122 lines (97 loc) · 4.82 KB

index.md

File metadata and controls

122 lines (97 loc) · 4.82 KB
Raw
title Docker socket proxy

Docker socket proxy

Dockman honors DOCKER_HOST. A proxy limits the Docker API routes exposed to the application and avoids mounting the raw socket into Dockman.

services:
  dockman:
    image: ghcr.io/cerede2000/dockman:integration
    environment:
      DOCKER_HOST: tcp://socketproxy:2375
      DOCKMAN_COMPOSE_ROOT: /server/stacks
    depends_on:
      socketproxy:
        condition: service_healthy

  socketproxy:
    image: lscr.io/linuxserver/socket-proxy:latest
    environment:
      LOG_LEVEL: info
      PING: 1
      VERSION: 1
      INFO: 1
      EVENTS: 1
      CONTAINERS: 1
      IMAGES: 1
      NETWORKS: 1
      VOLUMES: 1
      EXEC: 1
      POST: 1
      SYSTEM: 1
      ALLOW_START: 1
      ALLOW_STOP: 1
      ALLOW_RESTARTS: 1
      BUILD: 1
      GRPC: 1 # BuildKit's API: needed by Compose stacks with a build section
      AUTH: 0
      COMMIT: 0
      CONFIGS: 0
      DISTRIBUTION: 0
      NODES: 0
      PLUGINS: 0
      SERVICES: 0
      SESSION: 0
      SWARM: 0
      TASKS: 0
      SECRETS: 0
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    read_only: true
    tmpfs:
      - /run
      - /tmp
      - /var/lib/haproxy
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--spider", "http://127.0.0.1:2375/version"]
      interval: 30s
      timeout: 5s
      retries: 3
    restart: unless-stopped

Exact variable names depend on the proxy image. The example targets LinuxServer socket-proxy.

Permission matrix

Feature Required API groups
Monitor, details, stats CONTAINERS, INFO, EVENTS
Image inventory/check/update IMAGES, POST; registry digest checks do not require DISTRIBUTION
Networks and volumes NETWORKS, VOLUMES
Start/stop/restart/Compose POST, lifecycle allowances, containers/networks/volumes/images
Container terminal EXEC, POST
Container file browser containers/archive; EXEC for compatibility fallbacks
Prune SYSTEM, affected resource group and POST
Dockerfile/Buildx build BUILD, containers, images and permission to create/delete the temporary BuildKit helper
Compose stack with a build: section BUILD and GRPC (BuildKit's API; SESSION=1 also works, as a slower fallback)
Builds on a host with build limits ALLOW_ARCHIVE besides containers, images, EXEC, VOLUMES and POST; GRPC is not used
Protected socket-proxy update containers/images and lifecycle write access

POST=1 is essential for mutations. A read-only proxy filesystem does not make the Docker API read-only; API policy comes from the proxy variables.

Reduce privileges by feature

  • Set BUILD=0 and GRPC=0 if neither Dockerfile builds nor Compose stacks with a build: section are used.
  • Set EXEC=0 if neither terminal nor compatibility file browsing is needed.
  • Keep Swarm, plugins, nodes, secrets, configs and distribution disabled unless a verified Dockman feature requires them.
  • Do not expose port 2375 outside the private Docker network.

Troubleshooting

Reads work but actions fail

Verify POST, lifecycle allowances and the specific resource group. Inspect proxy logs for the denied method/path.

A Compose stack with build: fails with "403 Forbidden"

Compose builds through BuildKit's /grpc endpoint, which a proxy denies unless GRPC=1 is set; the error is then a bare HTML "403 Forbidden" page, and the proxy log shows POST /grpc refused. Allow GRPC=1 (SESSION=1 also works). Dockman appends this hint to the error when a build is refused. Builds from the Files view are not affected: they fall back without it.

A build on a host with build limits fails with "403 Forbidden"

The limited builder runs BuildKit in a container Dockman creates, and Buildx copies its configuration into it, which is a PUT on containers/{id}/archive. LinuxServer's socket-proxy refuses it unless ALLOW_ARCHIVE=1. Dockman appends this hint to the error.

Build succeeds but helper remains

Builder removal also uses Docker write APIs. The build log reports cleanup failure separately. Grant the narrow required delete operation and remove only confirmed orphan buildx_buildkit_dockman-* containers.

Update check reports a private image error

Current registry checks support public authentication challenges but do not store private-registry credentials yet. This is independent of Docker API proxy permissions.

Security boundary

A proxy is defense in depth, not a complete sandbox. Allowing container creation, arbitrary bind mounts and Exec can still provide host-level authority. Restrict who can access Dockman and who can reach the proxy network.

Resources: