여기서는 멈추세요
- daemon 시작 시 기존 컨테이너 자동 기동과 포트 노출 영향, 작업 전 서비스 상태를 확인하지 못했다면 start·restart하지 않습니다.
- docker.sock 권한을 666·777로 바꾸거나 TCP 2375를 TLS 없이 열라는 우회만 가능하다면 적용하지 않습니다.
- docker 그룹의 root 수준 권한을 승인받지 못했거나 rootless·rootful 운영 모델이 불명확하면 사용자 그룹을 변경하지 않습니다.
DOCKER ACCESS
Docker daemon·socket 권한 장애
Cannot connect와 permission denied를 daemon 중단, 잘못된 context·DOCKER_HOST, Unix socket 권한, rootless 모드로 나눠 과도한 chmod 없이 해결합니다.Cannot connect to the Docker daemonpermission denied docker.sockIs the docker daemon runningdocker group permissionDOCKER_HOSTrootless Docker
환경Docker Engine 28·29 계열 · systemd Linux · rootful 또는 rootless daemon
분류컨테이너
검토일2026-09-02
진행5단계 · 조회 우선
SAFE OPERATING BOUNDARY
중단·복구 기준부터 확인하세요
복구 기준
그룹 변경 전 id·getent 기록에서 docker 그룹원이 아니었고 이번 절차가 실제로 추가한 정확한 사용자만 sudo gpasswd -d '<APPROVED_USER>' docker로 제거합니다. 원래 그룹원이었으면 제거하지 않습니다. 모든 세션을 다시 시작해 검증합니다. daemon 시작은 작업 전 inactive였고 실행 중 컨테이너·의존 서비스가 없다는 승인이 있을 때만 원래 상태로 돌립니다. daemon.json 변경은 별도 백업 파일 복원과 dockerd --validate 성공 후 반영합니다.
담당자에게 전달할 자료
- docker context endpoint, docker.service·docker.socket·containerd 상태와 최초 journal 오류
- docker.sock의 경로·mode·owner:group, 대상 사용자의 변경 전·후 그룹 목록, rootless user unit 상태
- 변경 전후 docker version·info 결과와 그룹 승인·회수 기록
BEFORE YOU START
이런 증상에서 시작합니다
- Cannot connect to the Docker daemon at unix:///var/run/docker.sock
- permission denied while trying to connect to the Docker daemon socket
- docker.service가 failed 또는 inactive임
- sudo docker는 되지만 일반 사용자 docker 명령은 실패함
CHECK THE BRANCH
놓치기 쉬운 원인 분기
docker.service가 inactive·failed인 경우
socket 권한을 바꾸기 전에 daemon 로그와 unit 실패 이유를 확인합니다. daemon.json 문법, 디스크 부족, containerd 실패, 중복 dockerd 실행을 먼저 해결해야 합니다.
daemon은 active지만 permission denied인 경우
docker.sock의 소유자·그룹과 현재 사용자의 보조 그룹을 비교합니다. socket을 666·777로 열지 않으며 docker 그룹이 호스트 root 수준 권한을 부여한다는 점을 승인자가 이해해야 합니다.
DOCKER_HOST·context가 원격을 가리키는 경우
로컬 socket 문제처럼 보여도 선택된 context나 환경 변수가 잘못된 endpoint를 가리킬 수 있습니다. TLS 원격 context는 인증서를 끄지 말고 원래 context로 복원합니다.
rootless daemon을 사용하는 경우
시스템 docker.service와 /var/run/docker.sock이 아니라 사용자 systemd unit과 XDG_RUNTIME_DIR의 socket을 확인합니다. rootful docker 그룹 절차를 섞지 않습니다.
FOLLOW THE FLOW
순서대로 확인하기
조회시스템을 변경하지 않는 확인 단계
1분 점검: endpoint·daemon·socket 분류
현재 context와 endpoint, systemd 상태, socket 메타데이터를 확인해 연결 실패와 권한 실패를 구분합니다.
Docker context
docker context show
docker context inspect --format '{{json .Endpoints.docker.Host}}'daemon 상태
systemctl is-active docker.service docker.socket
systemctl status docker.service docker.socket --no-pager -l기본 socket 권한
stat -Lc '%A %a %U:%G %n' /var/run/docker.sock
id결과 읽기
daemon inactive·failed면 서비스 분기, active인데 socket group과 사용자 group이 다르면 권한 분기, endpoint가 unix:///var/run/docker.sock이 아니면 context 분기입니다.
다음 판단
chmod나 재설치부터 하지 말고 해당 분기의 읽기 전용 진단으로 이동합니다.
조회시스템을 변경하지 않는 확인 단계
daemon·containerd 로그와 설정 문법 확인
서비스 시작 실패 시 최근 로그, unit, daemon 설정을 확인합니다. 설정 파일을 수정하거나 daemon을 재시작하지 않습니다.
Docker·containerd 최근 로그
sudo journalctl -u docker.service -u containerd.service --since '-20 min' --no-pagerunit과 의존성
systemctl cat docker.service docker.socket
systemctl is-active containerd.servicedaemon 설정 검증
sudo dockerd --validate --config-file=/etc/docker/daemon.json디스크와 inode
df -hT / /var
df -ih / /var결과 읽기
invalid configuration, no space, containerd 연결 실패, unit override 충돌 중 어느 메시지가 최초 원인인지 봅니다.
다음 판단
설정 오류면 백업·diff를 준비하고, 디스크·containerd 원인이면 관련 가이드로 먼저 해결합니다.
조회시스템을 변경하지 않는 확인 단계
socket 경로와 사용자 권한 확인
socket까지의 디렉터리 권한, 실제 socket, 사용자 그룹을 비교합니다. ACL·chmod·chown은 아직 변경하지 않습니다.
socket 경로 권한
namei -l /var/run/docker.sock
getfacl /var/run/docker.sock 2>/dev/null대상 사용자 그룹 초기 상태
id '<APPROVED_USER>'
getent group dockerDocker 프로세스와 socket
ps -C dockerd -o pid,user,group,etime,cmd
sudo ss -lxnp | grep docker.sock결과 읽기
socket이 root:docker 660이고 사용자가 docker 그룹이 아니면 정책상 그룹 권한이 필요한지 결정합니다. 다른 소유권이면 비공식 설치·unit override 여부를 먼저 확인합니다.
다음 판단
docker 그룹의 root 수준 위험을 허용할 수 없다면 sudo 정책 또는 rootless 모드를 선택합니다.
조회시스템을 변경하지 않는 확인 단계
context·환경 변수·rootless 모드 확인
원격 context와 rootless user unit을 시스템 daemon과 구분합니다. 환경 변수 값에는 내부 주소가 있을 수 있어 공유 전 마스킹합니다.
전체 context 목록
docker context lsDocker 관련 환경 변수 이름
env | sed -n 's/^\(DOCKER_[A-Z_]*\)=.*/\1=<set>/p'rootless 사용자 daemon
systemctl --user status docker.service --no-pager -l
loginctl show-user "$(id -un)" -p Linger결과 읽기
rootless가 active면 사용자 socket/context를, 원격 context면 해당 endpoint TLS·접근 경로를 점검합니다. 둘 다 아니면 system daemon 분기로 돌아갑니다.
다음 판단
운영 모델을 rootful group, 제한된 sudo, rootless 중 하나로 명확히 정한 뒤 최소 변경만 승인합니다.
변경데이터·서비스 상태가 달라질 수 있는 단계
승인된 daemon 시작 또는 사용자 권한 반영
아래 두 분기 중 원인과 운영 정책에 맞는 하나만 실행합니다. docker 그룹은 root 수준 권한이며 socket 전체 공개는 금지합니다.
변경 단계입니다. 실행 전 대상 이름과 경로, 서비스 중단 영향, 복구 방법을 다시 확인하세요.
A. daemon 시작
sudo systemctl start docker.service
systemctl is-active docker.serviceB. 승인된 사용자만 docker 그룹 추가
sudo usermod -aG docker '<APPROVED_USER>'새 로그인 세션에서 검증
id
docker context show
docker version
docker info --format '{{json .ServerVersion}}'결과 읽기
Client와 Server 버전이 모두 표시되고 의도한 context에서만 명령이 성공해야 합니다. chmod 666/777이나 TCP 2375 무인증 노출은 정상 복구가 아닙니다.
다음 판단
실패하면 A는 daemon 로그와 작업 전 active 상태를 기준으로 복구합니다. B는 작업 전에는 그룹원이 아니었고 이번 절차가 실제로 추가한 사용자만 sudo gpasswd -d '<APPROVED_USER>' docker로 제거한 뒤 새 세션에서 확인합니다. 재발 방지를 위해 daemon.json 검증, 디스크·서비스 알림, docker 그룹 정기 감사를 운영 체크에 넣습니다.
PRIMARY REFERENCES
공식 문서
- Docker · Troubleshoot the daemon
- Docker · Read the daemon logs
- Docker · Linux post-installation steps
- Docker · Rootless mode
배포판과 버전에 따라 옵션·로그 위치가 다를 수 있습니다. 실행 전 서버의 --help와 로컬 매뉴얼을 함께 확인하세요.