Quick Reference

ip addr
ip route
ip route get 1.1.1.1
ss -tulpn
ss -ltnp
curl -I http://localhost:8080
curl -fsS --connect-timeout 3 --max-time 10 http://localhost:8080/health
curl -v https://example.com

진단 흐름

네트워크 문제는 DNS, route, TCP 연결, TLS, HTTP 응답을 분리해 봅니다. 먼저 이름이 기대한 IP로 해석되는지, 서버 자신에게 올바른 route가 있는지 확인합니다. 그다음 프로세스가 원하는 주소와 포트에서 listen 중인지, 마지막으로 실제 요청이 어느 단계에서 실패하는지 확인합니다.

ip addr
ip route
ss -ltnp
getent hosts example.com
curl -v https://example.com

getent hosts <name>은 현재 시스템의 name service 설정을 거친 DNS 결과를 확인합니다. ip route get <destination>은 default route 표만 보는 것보다 특정 목적지에 실제로 어떤 interface와 source address를 고를지 보여 줍니다. HTTPS 문제는 curl -v에서 DNS, TCP 연결, TLS certificate 검증, HTTP 응답 중 어디에서 멈췄는지 나눠 봅니다.

ss -ltnp는 TCP listen 포트와 프로세스 정보를 보여 줍니다. 권한이 부족하면 프로세스 이름이나 PID가 일부 보이지 않을 수 있으므로, 운영 서버에서는 필요한 경우 sudo ss -ltnp로 확인합니다.

localhost 성공과 외부 접속 성공은 다르다

curl http://localhost:8080이 성공해도 외부에서 접속 가능하다는 뜻은 아닙니다. 서비스가 127.0.0.1에만 바인딩되어 있으면 같은 서버 안에서는 접속되지만 외부에서는 접속할 수 없습니다. 외부 노출이 필요하면 listen 주소, 방화벽, 클라우드 보안 그룹, 포트 포워딩을 함께 확인해야 합니다.

ss -ltnp | grep 8080
curl -fsS http://127.0.0.1:8080/health
server_ip=203.0.113.10
curl -fsS "http://${server_ip}:8080/health"

curl -I는 HEAD 요청입니다. HEAD를 지원하지 않거나 GET과 다른 인증·라우팅 정책을 둔 endpoint라면 -I 성공이 실제 GET 성공을 보장하지 않습니다. health endpoint 확인에는 GET을 보내는 curl -fsS를 쓰고, 연결과 전체 요청이 오래 걸리지 않게 --connect-timeout과 --max-time을 서비스 성격에 맞춰 둡니다.

체크포인트

주의할 점

ss -ltnp | grep 8080
curl -fsS http://localhost:8080/health