Linux: "Connection refused" (ECONNREFUSED) 진단하기

안녕하세요, BlueByte입니다. 서비스에 닿아야 할 명령이 곧바로 Connection refused로 되돌아오는 경우가 있습니다 — curl: (7) Failed to connect to localhost port 8080: Connection refused, ssh: connect to host db01 port 22: Connection refused, 코드에서는 ConnectionRefusedError: [Errno 111] Connection refused. 다행히 이것은 빠르고 정직한 실패입니다: 호스트가 응답했고, 다만 거절한 것입니다. 오늘은 거부가 실제로 뜻하는 것, 네 가지 원인 중 어느 것인지 찾는 법, 원인별 해결, 그리고 연결이 완료되는지 확인하는 것까지 하나씩 짚어보겠습니다.

"Connection refused"의 뜻 — 타임아웃이 아니라 거절

거부는 반대편 커널이 "여기엔 아무것도 없다"고 적극적으로 말하는 것입니다. 여러분의 컴퓨터는 포트로 TCP SYN을 보냈는데, 핸드셰이크 대신 원격 커널이 RST로 답한 것입니다 — 아무 프로세스도 듣고 있지 않거나, 방화벽 규칙이 거절을 보냈기 때문입니다. 변형은 모두 같은 뜻입니다:

curl: (7) Failed to connect to localhost port 8080: Connection refused
nc: connect to 10.0.0.5 port 5432 (tcp) failed: Connection refused
ConnectionRefusedError: [Errno 111] Connection refused

curl은 이를 exit code 7이라 부르며, 자체 설명은 Failed to connect() to host or proxy입니다. 중요한 점은 거부가 즉시 일어난다는 것입니다. 응답이 밀리초 안에 돌아왔다면 호스트는 살아 있고 닿는 것이며, 문제는 네트워크가 아니라 포트입니다.

포트가 여러분을 거부하는 네 가지

• 아무것도 듣고 있지 않음 — 서비스가 멈췄거나 크래시했거나 애초에 시작되지 않아 포트가 닫혀 있습니다.
• 잘못된 인터페이스에서 듣고 있음 — 서비스가 127.0.0.1에 바인딩되어 로컬 클라이언트에는 답하고 원격은 모두 거부합니다.
• 포트가 틀림 — 클라이언트는 :8080을 가리키는데 서비스는 :8000에서 듣습니다.
• 방화벽이 거절 중 — 규칙이 REJECT(능동적인 RST나 ICMP)를 보내며, 이는 아무것도 듣지 않는 것과 똑같아 보입니다.

먼저 실제로 무엇이 듣고 있는지 묻기

클라이언트를 건드리기 전에 서버를 보세요. ss는 소켓을 나열합니다 — -t는 TCP, -l은 listening, -n은 이름 해석 생략, -p는 소유 프로세스:

ss -tlnp | grep 8080

LISTEN 0  511  127.0.0.1:8080  0.0.0.0:*  users:(("gunicorn",pid=812,fd=7))

아무것도 반환하지 않으면 듣는 게 없는 것 — 첫 번째 원인입니다. 한 줄이 나오면 로컬 주소를 유심히 읽으세요; 그게 다음 확인 대상입니다.

바인드 주소 읽기: 127.0.0.1 대 0.0.0.0

포트 앞의 주소가 전부입니다. 127.0.0.1:8080은 서비스가 같은 컴퓨터에서 오는 연결만 받는다는 뜻이라 — 원격 클라이언트, 심지어 다른 인터페이스의 컨테이너도 Connection refused를 받습니다. 0.0.0.0:8080(또는 *:8080)은 모든 인터페이스에서 듣는다는 뜻입니다. 그래서 위 출력에서는 로컬 curl은 되지만 원격에서 이 장비를 치는 동료는 거부됩니다 — 방화벽이 아니라 바인드 주소 때문입니다. 한 가지 함정이 사람을 걸려 넘어뜨립니다: 많은 시스템에서 localhost가 ::1(IPv6)로 먼저 해석되므로, 서비스가 IPv4 127.0.0.1에만 바인딩했다면 ::1로 가는 클라이언트는 거부되고 127.0.0.1은 됩니다. curl -4나 curl -6으로 계열을 강제해 어느 쪽이 빠졌는지 보세요.

curl과 nc로 경로 증명하기

클라이언트 쪽에서 서버가 무엇을 하는지 확인하세요:

curl -v http://db01:8080/ ; echo "exit: $?"
nc -vz db01 8080

*   Trying 10.0.0.5:8080...
* connect to 10.0.0.5 port 8080 failed: Connection refused
exit: 7
nc: connect to db01 (10.0.0.5) port 8080 (tcp) failed: Connection refused

curl -v는 이름을 해석하고 IP에 닿은 뒤 거부됐음을 보여 줍니다 — 즉 DNS는 멀쩡하고 호스트는 살아 있습니다. exit: 7은 타임아웃이 아니라 거부임을 확인해 줍니다. nc -vz는 요청을 보내지 않고 같은 한 줄 판정을 줍니다.

원인별 해결: 시작하거나, 재바인딩하거나, 열기

1. 듣는 게 없음 — 서비스를 시작하고 올라왔는지 확인:

sudo systemctl start myapp
ss -tlnp | grep 8080

2. 잘못된 인터페이스 — 서비스의 listen 주소를 127.0.0.1에서 0.0.0.0(또는 특정 인터페이스)으로 바꾸고, 재시작한 뒤 ss로 다시 확인하세요. 소켓이 이제 0.0.0.0:8080으로 보여야 합니다.

3. 잘못된 포트 — ss가 실제로 보여 주는 포트로 클라이언트를 맞추세요.

4. 방화벽 거절 — 규칙을 살펴보고 포트를 허용하세요:

sudo nft list ruleset | grep -i reject
sudo iptables -L -n | grep 8080

REJECT 규칙은 닫힌 포트처럼 즉시 거부하고, DROP 규칙은 대신 클라이언트가 타임아웃까지 멈춰 있게 합니다. 그러니 ss가 리스너를 보여 주는데도 클라이언트가 빠르게 거부되면 REJECT 규칙을 콕 집어 찾으세요 — DROP이라면 거부가 아니라 타임아웃으로 나타납니다.

실제 사례: localhost에서만 듣는 앱

한 동료가 10.0.0.5:8080의 웹 앱에 닿지 못하고 곧바로 Connection refused를 받습니다. ping은 되므로 호스트는 살아 있습니다. 서버에서 ss -tlnp | grep 8080은 127.0.0.1:8080을 보여 줍니다 — 앱이 localhost에 바인딩된 것입니다. 설정을 0.0.0.0:8080에서 듣도록 고치고 sudo systemctl restart myapp을 실행하니 ss가 이제 0.0.0.0:8080을 보여 줍니다. 동료의 컴퓨터에서 curl -sS http://10.0.0.5:8080/이 페이지를 돌려줍니다. 네트워크나 방화벽에는 아무 문제가 없었고, 서비스가 그저 자기 자신 말고는 포트를 내주지 않았을 뿐입니다.

연결이 실제로 완료되는지 확인하기

고친 뒤에는 요청이 거부가 아니라 진짜 응답을 받아야 합니다:

curl -sS -o /dev/null -w "%{http_code}\n" http://db01:8080/health

200

상태 코드가 돌아오면 — 404라도 — TCP 연결이 성공했고 무언가 응답했다는 뜻입니다. ss -tlnp가 기대하는 인터페이스에서 서비스를 보여 주는 것과 함께 확인하세요.

재발 방지, 그리고 타임아웃과의 차이

서비스를 실제로 의도한 인터페이스에 바인딩하고, 크래시한 서비스를 사용자가 거부를 만나기 전에 알아채도록 시작 헬스체크를 두고, 클라이언트가 엉뚱한 포트로 흘러가지 않게 각 서비스의 포트를 문서화하세요. 이것은 Connection timed out(curl exit 28)과는 다른 실패입니다: 타임아웃은 침묵입니다 — 패킷이 방화벽 DROP 규칙에 버려졌거나 호스트가 죽어 있어, 클라이언트가 기다리다 결국 포기합니다. 거부는 즉각적인 거절입니다. 그리고 둘 다 Could not resolve host(curl exit 6)와도 다릅니다 — 그것은 TCP를 시도하기도 전에 DNS에서 실패합니다. 다음에 Connection refused를 보면, 서버의 ss부터 시작하세요: 무언가 듣고 있는가, 그리고 어느 주소에서인가.