How to fix Error response from daemon: operation not permitted: capability not permitted in Docker

First, determine which capability your application needs. Common capabilities and their use cases:

| Capability | Purpose |
|------------|---------|
| CAP_NET_ADMIN | Network interface configuration, iptables, routing |
| CAP_SYS_ADMIN | Mount operations, namespace management, many admin tasks |
| CAP_NET_RAW | Raw socket access, ping, packet capture |
| CAP_SYS_PTRACE | Debugging, strace, process inspection |
| CAP_IPC_LOCK | Memory locking (mlock, mlockall) |
| CAP_SYS_TIME | System clock modification |

Check what your application is trying to do:

# Run with strace to see failing syscalls
docker run --rm -it --cap-add SYS_PTRACE your-image strace -f your-command 2>&1 | grep -i "permission denied\|operation not permitted"

Common operations and their required capabilities:

- ip link, ip addr, iptables -> CAP_NET_ADMIN
- mount, umount -> CAP_SYS_ADMIN
- ping (ICMP) -> CAP_NET_RAW
- strace, gdb -> CAP_SYS_PTRACE

Once you know which capability is needed, add it using the --cap-add flag. Always prefer adding specific capabilities over using --privileged.

Add a single capability:

# For network administration (iptables, ip commands)
docker run --cap-add NET_ADMIN your-image

# For system administration tasks
docker run --cap-add SYS_ADMIN your-image

# For raw network access
docker run --cap-add NET_RAW your-image

Add multiple capabilities:

docker run --cap-add NET_ADMIN --cap-add SYS_ADMIN your-image

Note: Docker uses capability names without the CAP_ prefix. Use NET_ADMIN not CAP_NET_ADMIN.

In Docker Compose:

version: "3"
services:
  myapp:
    image: your-image
    cap_add:
      - NET_ADMIN
      - SYS_ADMIN

Confirm which capabilities your container actually has:

Check current capabilities inside the container:

# Run an interactive shell with your capabilities
docker run --rm -it --cap-add NET_ADMIN ubuntu:22.04 bash

# Inside the container, check capabilities
apt-get update && apt-get install -y libcap2-bin
capsh --print

Expected output will show capabilities like:

Current: cap_chown,cap_dac_override,...,cap_net_admin,...
Bounding set: cap_chown,cap_dac_override,...,cap_net_admin,...

Check capabilities of running containers:

# List capabilities for all containers
docker ps -q | xargs docker inspect --format '{{.Name}}: CapAdd={{.HostConfig.CapAdd}} CapDrop={{.HostConfig.CapDrop}}'

Test if the capability works:

# Test NET_ADMIN capability
docker run --rm --cap-add NET_ADMIN ubuntu:22.04 ip link set lo down && echo "Success" || echo "Failed"

Even with the right capability, seccomp (secure computing mode) may block the required system calls.

Test with seccomp disabled (for debugging only):

docker run --security-opt seccomp=unconfined --cap-add NET_ADMIN your-image

If this works, create a custom seccomp profile:

1. Get Docker's default seccomp profile:

curl -o default-seccomp.json https://raw.githubusercontent.com/moby/moby/master/profiles/seccomp/default.json

2. Modify it to allow required syscalls
3. Use your custom profile:

docker run --security-opt seccomp=custom-seccomp.json --cap-add NET_ADMIN your-image

Warning: Disabling seccomp reduces container security. Only disable for debugging or use a minimal custom profile that allows only required syscalls.

Security modules like AppArmor (Ubuntu/Debian) or SELinux (RHEL/CentOS) may also block operations.

For AppArmor (Ubuntu/Debian):

# Test with AppArmor disabled (debugging only)
docker run --security-opt apparmor=unconfined --cap-add NET_ADMIN your-image

If you see unknown AppArmor profiles causing issues:

# Remove unknown AppArmor profiles
sudo aa-remove-unknown

For SELinux (RHEL/CentOS/Fedora):

# Check SELinux denials
sudo ausearch -m avc -ts recent

# Test with SELinux in permissive mode (debugging only)
docker run --security-opt label=disable --cap-add NET_ADMIN your-image

Create custom policies for production rather than disabling security modules.

Running Docker inside LXC or Docker-in-Docker has additional restrictions.

For Docker-in-Docker:

# Run with privileged mode (use with caution)
docker run --privileged -v /var/run/docker.sock:/var/run/docker.sock docker:latest

# Or with specific capabilities for DinD
docker run --cap-add SYS_ADMIN --cap-add NET_ADMIN \
  --security-opt seccomp=unconfined \
  --security-opt apparmor=unconfined \
  docker:dind

For Docker inside LXC:

1. Enable nesting in LXC:

# In LXC config
lxc.include = /usr/share/lxc/config/nesting.conf

2. Grant required capabilities to the LXC container:

# In Proxmox, enable nesting and FUSE in container options
# Or manually add to config:
lxc.cap.drop =
features: nesting=1

For Proxmox: Ensure virtualization is enabled in BIOS and the container has nesting enabled.

The --privileged flag grants all capabilities and disables security restrictions. Use only when absolutely necessary.

Run a privileged container:

docker run --privileged your-image

What --privileged does:
- Grants ALL Linux capabilities
- Disables seccomp filtering
- Gives access to all host devices
- Mounts /dev and /sys as read-write
- Essentially gives container root-level access to the host

Security implications:
- Container can escape to the host
- Container can access host devices
- Container can modify host kernel parameters
- Breaks container isolation model

Better alternative - identify minimum required capabilities:

# Instead of --privileged, use only what you need
docker run \
  --cap-add NET_ADMIN \
  --cap-add SYS_ADMIN \
  --cap-add MKNOD \
  your-image

In production, always prefer specific capabilities over --privileged.

For containers running in Kubernetes, configure capabilities in the pod security context.

Add capabilities in Kubernetes:

apiVersion: v1
kind: Pod
metadata:
  name: capability-pod
spec:
  containers:
  - name: app
    image: your-image
    securityContext:
      capabilities:
        add:
          - NET_ADMIN
          - SYS_ADMIN

Drop all and add specific (recommended):

securityContext:
  capabilities:
    drop:
      - ALL
    add:
      - NET_ADMIN

For privileged pods (use sparingly):

securityContext:
  privileged: true

Note: Pod Security Policies (PSP) or Pod Security Standards may restrict capabilities. Check with your cluster admin if capabilities are being dropped at the policy level.