┌─────────────────────────────────────────────────────────┐
│                     User Space                          │
│                                                         │
│  docker CLI ──REST──▶ dockerd                           │
│                          │                              │
│                       gRPC (containerd.sock)            │
│                          ▼                              │
│                      containerd                         │
│                          │   image pull / snapshots     │
│                          │                              │
│              fork/exec   ▼                              │
│           containerd-shim-runc-v2  ◀── stays alive      │
│                          │                              │
│               fork/exec  ▼  (exits after start)        │
│                        runc                             │
│                          │  clone(2) + pivot_root       │
│                          ▼                              │
│                   container init (PID 1)                │
│                                                         │
└─────────────────────────────────────────────────────────┘
         │              │               │
    Namespaces       cgroups v2      OverlayFS
  (pid/net/mnt…)  (cpu/mem/io…)   (layers + rw)

{
  "storage-driver": "overlay2",
  "log-driver": "json-file",
  "log-opts": { "max-size": "20m", "max-file": "3" },
  "default-address-pools": [{ "base": "172.30.0.0/16", "size": 24 }],
  "dns": ["8.8.8.8"],
  "live-restore": true   // keep containers running if dockerd restarts
}

# list containerd namespaces (docker uses "moby")
ctr namespaces list

# list images in the moby namespace
ctr -n moby images list

# list running tasks (containers)
ctr -n moby tasks list

# pull an image directly via containerd
ctr images pull docker.io/library/nginx:latest

# show snapshots for a container
ctr -n moby snapshots ls

/run/containerd/io.containerd.runtime.v2.task/moby/<id>/
  ├── config.json     # OCI runtime spec (namespaces, cgroups, caps, mounts…)
  ├── rootfs/         # merged OverlayFS mount (container filesystem)
  ├── init.pid        # PID of container init written by shim
  └── log.json        # shim log

containerd-shim
  │
  └── fork/exec runc create <bundle>
        │
        ├── parse config.json
        ├── clone(CLONE_NEWPID | CLONE_NEWNET | CLONE_NEWNS | …)
        │     └─ child enters new namespaces
        ├── pivot_root  → container rootfs becomes /
        ├── mount /proc, /sys, /dev, bind mounts, volumes
        ├── apply cgroup limits  (write to /sys/fs/cgroup/…)
        ├── drop capabilities
        ├── apply seccomp filter
        └── execve(entrypoint)  → container PID 1
              │
              └── runc exits; shim holds stdio fds open

# dump the full OCI config for a running container
docker inspect --format '{{json .}}' <container> | jq .

# read runc state directly
runc state <container-id>

# show the OCI bundle config
cat /run/containerd/io.containerd.runtime.v2.task/moby/<id>/config.json | jq .

 docker CLI
    │  POST /containers/create  (REST)
    ▼
 dockerd
    │  1. resolve image (pull if missing via containerd)
    │  2. create container record (assign ID, copy config)
    │  3. set up networking (allocate IP, create veth pair, iptables rules)
    │  4. prepare OCI bundle (write config.json, set up OverlayFS mount)
    │
    │  NewContainer() gRPC → containerd
    ▼
 containerd
    │  5. prepare snapshot (OverlayFS upperdir for this container)
    │  6. fork containerd-shim-runc-v2
    │
    │  shim.Create() → shim
    ▼
 containerd-shim
    │  7. fork/exec runc create --bundle <path>
    │
    ▼
 runc
    │  8.  clone(2) with namespace flags
    │  9.  child: pivot_root, mount /proc /sys /dev, bind mounts
    │  10. write cgroup limits to /sys/fs/cgroup/<container-id>/
    │  11. drop capabilities, apply seccomp filter
    │  12. write PID to init.pid, signal parent
    │  13. execve(entrypoint) → container PID 1 starts
    │  14. runc exits
    ▼
 containerd-shim (alive)
    │  holds stdio pipes, waits for PID 1 exit
    ▼
 container process (PID 1 inside namespace)
    └── nginx, bash, your app…

# list namespaces of a running container's PID
PID=$(docker inspect -f '{{.State.Pid}}' <container>)
ls -la /proc/$PID/ns/

# enter the container's network namespace from the host
nsenter -t $PID -n ip addr

# enter all namespaces (like docker exec)
nsenter -t $PID --all -- bash

# show namespace IDs — containers sharing a net ns (--network container:X)
lsns -p $PID

/sys/fs/cgroup/
  └── system.slice/
        └── docker-<container-id>.scope/
              ├── memory.max          # hard memory limit
              ├── memory.high         # soft limit (throttle before OOM)
              ├── cpu.max             # "quota period" e.g. "50000 100000" = 50% CPU
              ├── cpu.weight          # relative CPU shares
              ├── io.max              # device read/write bps and iops limits
              ├── pids.max            # max PIDs (prevents fork bombs)
              └── cgroup.procs        # PIDs in this cgroup

# find the cgroup path for a container
CID=$(docker inspect -f '{{.Id}}' <container>)
cat /proc/$(docker inspect -f '{{.State.Pid}}' <container>)/cgroup

# read current memory usage (cgroups v2)
cat /sys/fs/cgroup/system.slice/docker-${CID}.scope/memory.current

# read cpu usage stats
cat /sys/fs/cgroup/system.slice/docker-${CID}.scope/cpu.stat

# live resource stats
docker stats <container>

# check if cgroups v2 is active
stat -f -c '%T' /sys/fs/cgroup   # "cgroup2fs" = v2, "tmpfs" = v1

# drop all capabilities, add back only what's needed
docker run --cap-drop ALL --cap-add NET_BIND_SERVICE nginx

# run privileged (all capabilities + device access — avoid in prod)
docker run --privileged ...

# inspect effective capabilities of a running container process
PID=$(docker inspect -f '{{.State.Pid}}' <container>)
grep CapEff /proc/$PID/status | awk '{print $2}' | xargs -I{} capsh --decode={}

# check at runtime inside container
docker exec <container> capsh --print

# trace syscalls to find what's being blocked (EPERM / ENOSYS)
docker run --security-opt seccomp=unconfined --rm \
  strace -f -e trace=all myapp 2>&1 | grep -E "EPERM|ENOSYS"

# view Docker's default seccomp profile
curl -s https://raw.githubusercontent.com/moby/moby/master/profiles/seccomp/default.json | jq .syscalls[].names

  Container view (merged)
  ─────────────────────────────────
  /etc/nginx/nginx.conf   ◀── from upperdir (modified)
  /usr/sbin/nginx         ◀── from lowerdir layer 3 (image)
  /lib/x86_64-linux-gnu/  ◀── from lowerdir layer 1 (base)

  OverlayFS mount:
    lowerdir = layer3:layer2:layer1   (read-only, :-separated, top-to-bottom)
    upperdir = /var/lib/docker/overlay2/<id>/diff    (read-write)
    workdir  = /var/lib/docker/overlay2/<id>/work    (kernel internal)
    merged   = /var/lib/docker/overlay2/<id>/merged  (container rootfs)

# show overlay mount options for a running container
docker inspect -f '{{json .GraphDriver}}' <container> | jq .

# same info from the host mount table
mount | grep overlay

# look at the writable layer diff (files changed by the container)
UPPER=$(docker inspect -f '{{.GraphDriver.Data.UpperDir}}' <container>)
ls $UPPER

# see all image layers for an image
docker inspect nginx | jq '.[].RootFS.Layers'

# layer directories on disk
ls /var/lib/docker/overlay2/

OCI Image Index (manifest list)
  └── Manifest (per platform)
        ├── Config JSON   { "Cmd": [...], "Env": [...], "RootFS": { "diff_ids": [...] } }
        └── Layers []     [ sha256:abc… (tar.gz), sha256:def… (tar.gz), … ]
                               ▲
                          content-addressed blobs
                          /var/lib/docker/image/overlay2/layerdb/sha256/<digest>/

# Bad: COPY invalidates cache early, re-runs npm install every code change
COPY . /app
RUN npm install

# Good: copy dependencies first, code second
COPY package.json package-lock.json /app/
RUN npm install           # cached as long as package*.json unchanged
COPY . /app               # invalidated only when source changes

# show layer history and sizes
docker history nginx

# detailed layer info
docker inspect nginx | jq '.[].RootFS'

# export a container filesystem (flattened, no layers)
docker export <container> | tar -tv

# save image with all layers as a tar archive
docker save nginx | tar -tv

# show total disk usage by images/containers/volumes
docker system df -v

# named volume
docker run -v mydata:/var/lib/postgresql/data postgres

# bind mount (absolute host path)
docker run -v /host/config:/etc/app/config:ro myapp

# tmpfs for secrets
docker run --tmpfs /run/secrets:rw,noexec,nosuid,size=64m myapp

# inspect mount details
docker inspect -f '{{json .Mounts}}' <container> | jq .

# list volumes
docker volume ls
docker volume inspect mydata

 Host network namespace
 ┌──────────────────────────────────────────────────────┐
 │                                                      │
 │   eth0 ──── docker0 (bridge 172.17.0.1/16)           │
 │                  │                                   │
 │            ┌─────┴──────┐                            │
 │         veth0a        veth0b  …(one pair per container)
 │            │                                         │
 └────────────┼─────────────────────────────────────────┘
              │ (peer end inside container net namespace)
 Container net namespace
 ┌────────────────────────────────────────┐
 │  eth0  172.17.0.2/16                  │
 │  lo    127.0.0.1/8                    │
 │  default gw: 172.17.0.1 (docker0)    │
 └────────────────────────────────────────┘

# create a user-defined bridge network
docker network create --driver bridge --subnet 192.168.10.0/24 mynet

# attach containers — they resolve each other by name
docker run -d --name db --network mynet postgres
docker run -d --name app --network mynet myapp
# app can reach db at hostname "db"

# inspect network
docker network inspect mynet

# see the bridge on the host
ip link show type bridge
brctl show

# what dockerd/containerd do under the hood (simplified)
ip link add veth0a type veth peer name veth0b    # create pair
ip link set veth0b netns <container-netns>       # move peer into container ns
ip link set veth0a master docker0                # attach host end to bridge
ip link set veth0a up

# inside the container namespace
ip link set veth0b name eth0
ip addr add 172.17.0.2/16 dev eth0
ip link set eth0 up
ip route add default via 172.17.0.1

# view Docker's iptables rules
iptables -t nat -L -n --line-numbers
iptables -L DOCKER -n --line-numbers

# MASQUERADE rule: outbound container traffic → NAT to host IP
-A POSTROUTING -s 172.17.0.0/16 ! -o docker0 -j MASQUERADE

# DNAT rule for port mapping (-p 8080:80)
-A DOCKER -i eth0 -p tcp --dport 8080 -j DNAT --to-destination 172.17.0.2:80

# DOCKER-ISOLATION chain blocks inter-bridge traffic
-A DOCKER-ISOLATION-STAGE-1 -i docker0 ! -o docker0 -j DOCKER-ISOLATION-STAGE-2

# incoming packet to host port 8080 → container:80
Host:8080 ──DNAT──▶ 172.17.0.2:80 ──veth──▶ container eth0:80

# verify port mapping
docker port <container>
iptables -t nat -L DOCKER -n | grep 8080

Container
  └── /etc/resolv.conf
        nameserver 127.0.0.11           ◀── Docker embedded resolver
        options ndots:0

Container makes DNS query for "db"
  │
  ▼
127.0.0.11 (embedded resolver, inside net ns)
  │
  ├── name matches a container on the same network? → return its IP
  ├── name matches a network alias?               → return aliased IP
  ├── name matches a Swarm service?               → return VIP
  └── unknown → forward to host resolver (/etc/resolv.conf on host)

# verify container DNS config
docker exec <container> cat /etc/resolv.conf

# resolve a peer container name from inside
docker exec app nslookup db

# assign a network alias (multiple names for one container)
docker run --network mynet --network-alias cache redis

# override DNS server for a container
docker run --dns 1.1.1.1 myapp

# set search domains
docker run --dns-search internal.corp myapp

# host networking
docker run --network host nginx
# nginx binds to host :80 directly — no port mapping needed

# macvlan network (container gets a real LAN IP)
docker network create \
  --driver macvlan \
  --subnet 192.168.1.0/24 \
  --gateway 192.168.1.1 \
  -o parent=eth0 \
  macnet

docker run --network macnet --ip 192.168.1.50 nginx

## Container internals
docker inspect <container>                      # full JSON config + state
docker inspect -f '{{.State.Pid}}' <container>  # host PID of container init
docker inspect -f '{{json .HostConfig}}' <c> | jq .  # resource limits
docker top <container>                          # processes inside
docker stats <container>                        # live cpu/mem/io/net
docker diff <container>                         # changed files (upperdir diff)

## Filesystem
docker inspect -f '{{.GraphDriver.Data.MergedDir}}' <c>   # merged view
docker inspect -f '{{.GraphDriver.Data.UpperDir}}' <c>    # writable layer

## Namespaces from host
PID=$(docker inspect -f '{{.State.Pid}}' <container>)
ls -la /proc/$PID/ns/
nsenter -t $PID -n -- ip addr                   # host-side net namespace entry

## cgroups
CID=$(docker inspect -f '{{.Id}}' <container>)
cat /sys/fs/cgroup/system.slice/docker-${CID}.scope/memory.current
cat /sys/fs/cgroup/system.slice/docker-${CID}.scope/cpu.stat

## containerd / runc state
ctr -n moby tasks list
runc state $CID
runc list

# check active storage driver
docker info | grep "Storage Driver"

# check backing filesystem
docker info | grep "Backing Filesystem"

# switch to overlay2 in daemon.json
# { "storage-driver": "overlay2" }
# then: systemctl restart docker  (existing images/containers lost)