term-meshd 종료 hang으로 재시작 중 relay가 90초간 거부됨

[JINWOO-J]

현상

Linux peer host root@<peer-host>에서 term-meshd 0.214.0 설치·재시작 중 relay 접속이 약 90초 동안 계속 Connection refused가 됐다.

서버와 SSH는 정상 상태였지만, 기존 데몬이 relay/control socket을 닫은 뒤 종료되지 않아 새 데몬이 systemd의 종료 제한까지 시작하지 못했다.

확인된 타임라인

서버 시각은 UTC다.

2026-08-25 22:55:56  기존 term-meshd가 SIGTERM 수신
2026-08-25 22:55:56  headless agents terminated
2026-08-25 22:55:56  agent sessions terminated
2026-08-25 22:55:56  /run/term-mesh/term-meshd.sock 제거
2026-08-25 22:55:56  peer server shutting down
                         이후 종료 진행 로그 없음
2026-08-25 22:57:26  systemd TimeoutStopSec=90s 만료, SIGKILL
2026-08-25 22:57:26  새 term-meshd 시작
2026-08-25 22:57:26  control socket LISTEN
2026-08-25 22:57:26  peer socket LISTEN

관련 로그:

received SIGTERM, initiating graceful shutdown...
headless agents terminated
agent sessions terminated
removed socket file /run/term-mesh/term-meshd.sock
term-meshd.service: State 'stop-sigterm' timed out. Killing.
term-meshd.service: Killing process 1017411 (term-meshd) with signal SIGKILL.
term-meshd.service: Main process exited, code=killed, status=9/KILL
term-meshd.service: Failed with result 'timeout'.
Started term-mesh peer host.
listening on /run/term-mesh/term-meshd.sock
peer-federation listening on /run/term-mesh/tm-peer.sock

분석

종료는 agent sessions terminated 이후, server join 이전에서 멈춘 것으로 보인다.

daemon/term-meshd/src/main.rs에서 바로 다음 단계는 monitor_handle.resume_all_stopped()다. server join에는 5초 timeout이 있지만 다음 로그가 모두 없었으므로 server join까지 도달하지 않았다.

servers shut down cleanly
server shutdown timed out after 5s
shutdown complete

당시 stack dump가 없어 resume_all_stopped() 내부에서 멈췄는지, 그 직전/직후 runtime이 정체됐는지는 아직 확정되지 않았다.

과거 PrivateTmp=true 때문에 control socket이 SSH mount namespace에서 보이지 않았던 문제와는 별개다. 이 서버에는 현재 다음 설정이 적용되어 있고, 재시작 후 두 socket 모두 정상 동작한다.

TERMMESH_DAEMON_UNIX_PATH=/run/term-mesh/term-meshd.sock
TERMMESH_PEER_SOCKET=/run/term-mesh/tm-peer.sock

영향

• upgrade/reinstall/restart 때 relay가 최대 90초간 접속 불가
• 클라이언트는 해당 구간 내내 Connection refused로 재시도
• socket을 먼저 닫으므로 기존 relay 연결도 끊김
• Restart=always여도 기존 프로세스가 끝나기 전에는 새 listener가 뜨지 않음

기대 동작

• SIGTERM 후 종료가 정해진 짧은 시간 안에 완료되어야 한다.
• 종료 단계 하나가 멈춰도 전체 종료가 systemd의 90초 제한까지 대기하지 않아야 한다.
• 어느 종료 단계가 지연됐는지 로그로 식별할 수 있어야 한다.

수정 방향

• resume_all_stopped() 진입·완료와 server join 진입을 계측한다.
• 종료 단계마다 bounded timeout을 적용한다.
• hang 시 남아 있는 task, lock 또는 process 정보를 기록한다.
• Linux service restart E2E에서 relay socket 부재 시간을 측정하고 상한을 검증한다.
• TimeoutStopSec 단축은 피해 시간을 줄이는 보조책일 뿐, 종료 hang 자체를 고쳐야 한다.

재발 확인 (2026-08-27)

동일한 Linux peer host에서 같은 증상이 다시 발생했다.

2026-08-27 05:35:57  systemd Stopping term-meshd.service
                         이후 term-meshd 로그 없음
2026-08-27 05:37:27  TimeoutStopSec 만료, SIGKILL

이번에는 received SIGTERM, initiating graceful shutdown... 조차 기록되지 않았다.
8월 25일 사례보다 더 이른 지점에서 멈췄는지, 로그가 출력되지 않았을 뿐인지는
현재 계측으로 구분할 수 없다. 종료 단계 계측이 필요하다는 근거가 하나 더 늘었다.

[JINWOO-J]

현 상태를 정리합니다. 종료 코드의 방어는 들어갔지만 issue는 아직 open이 맞습니다.\n\n구현 완료:\n- shutdown 단계 이름/계측\n- 전체 30초 watchdog\n- headless agents, agent sessions, stopped-process resume, server join별 bounded timeout\n- resume_all_stopped를 blocking pool로 분리\n- runtime stall 시 현재 shutdown step을 journal에서 식별\n\n남은 acceptance:\n- Linux systemd service restart E2E\n- SIGTERM부터 새 relay socket LISTEN까지 실제 부재 시간 측정\n- 반복 restart에서 상한 검증 및 90초 TimeoutStopSec 회귀 방지\n- stall injection으로 각 단계 timeout 이후에도 process가 최종 종료되는지 검증\n\n코드상 unbounded step은 방어됐지만 production-like restart proof가 없으므로 close하지 않습니다.

[JINWOO-J]

남은 acceptance 중 계측·회귀 부분을 채웠습니다. #465가 3d450b0e로 develop에 병합됐습니다. real host 실행이 남아 issue는 계속 open입니다.

문제 인식

2026-08-28의 d78dc4e5로 단계별 bound는 들어갔지만, 그것을 실행시키는 것이 아무것도 없었습니다. 단계가 반환을 멈추는 상황은 평범한 데몬 상태로는 만들어지지 않으므로, 보고된 두 hang 형태는 한 번도 재현된 적이 없었습니다.

구현

결함 주입 — TERMMESH_SHUTDOWN_STALL이 두 형태를 각각 재현합니다.

• 단계 이름(headless, agents, resume, servers): 그 단계의 future를 멈춰 세웁니다. 자기 제한 시간이 종료시키고 teardown은 계속 진행됩니다. 로그가 한 단계 뒤에서 끊긴 2026-08-25 형태입니다.
• teardown: 아무것도 로그하기 전에 teardown 스레드를 블록합니다. 그 런타임의 모든 bound가 무력화되어 런타임 밖 hard-exit 스레드만 프로세스를 끝낼 수 있습니다. SIGTERM 수신 로그조차 없던 2026-08-27 형태입니다.

인식하지 못한 값은 아무것도 주입하지 않으므로 오타로 프로덕션 데몬이 멈추지 않습니다.

측정 테스트 — daemon/term-meshd/tests/shutdown_restart.rs가 실제 바이너리를 격리된 소켓과 임시 HOME으로 띄워 클라이언트가 겪는 공백을 잽니다.

TimeoutStopSec=45 — system·user 두 unit 모두 값이 없어 배포판 기본값 90초를 상속하고 있었습니다. 이 issue 제목의 그 90초입니다. 데몬 자체 예산(30초)보다 크고 90초보다 작은 값을 모든 unit이 선언하는지 테스트가 강제하고, scripts/test-install-linux.sh가 설치된 unit에 그 줄이 있는지 확인합니다.

scripts/test-daemon-systemd-restart.sh — 실제 systemd에서 같은 공백을 재는 스크립트. 서비스를 재시작하므로 --yes 없이는 거부합니다.

측정 결과

cargo test -p term-meshd --test shutdown_restart → 4 passed (32초)

테스트	측정
3회 재시작	relay 공백이 초 단위, stop timeout 근처에도 못 감
agents 단계 stall	12초 제한에서 종료, 저널이 단계 이름 지목, shutdown complete까지 진행, exit 0
teardown wedge	30초 예산 안에 강제 종료 코드 2
unit 상한	모든 unit이 예산 초과·90초 미만의 TimeoutStopSec 선언

cargo test -p term-meshd --bin term-meshd shutdown → 13 passed.

기록해 둘 함정

stall 테스트 초기 버전은 stall이 적용되지 않은 채 통과했습니다. 두 서버가 started 영수증을 올리기 전에 SIGTERM을 보내면 "필수 서버 startup 실패"로 판정돼 agent 단계를 의도적으로 건너뛰기 때문입니다. teardown이 231ms에 끝났는데도 < AGENT_LIMIT + slack 단언은 통과했습니다.

connect 성공은 준비 증거가 못 됩니다. 두 리스너 모두 이후 startup 작업보다 먼저 bind하므로, 커널이 backlog로 연결을 받는 동안 데몬은 그 서버를 아직 started로 세지 않습니다. 지금은 control 서버의 실제 응답과 peer 서버의 자체 영수증을 준비 조건으로 씁니다. 단언에는 teardown >= AGENT_LIMIT를 추가해 stall 미적용을 잡아냅니다.

남은 acceptance

실제 Linux peer host에서 scripts/test-daemon-systemd-restart.sh --yes를 돌리는 것 하나입니다. 반복 재시작에서의 실제 부재 시간과 90초 회귀 부재를 real systemd로 확인하는 단계이고, 서비스를 재시작하므로 그 호스트의 relay 세션이 끊깁니다. 실행 시점 판단이 필요해 하지 않았습니다.

[JINWOO-J]

실제 Linux peer host에서 측정했습니다. PASS이고, 1라운드에서 이 이슈가 추정했던 hang을 실제로 잡았습니다.

측정 조건

root@jw-server, term-meshd 0.222.0. 이 구성이 중요합니다.

• 경계가 걸린 shutdown 코드는 들어 있습니다 (d78dc4e5, v0.216.0부터)
• unit에 TimeoutStopSec이 없습니다. 배포판 기본 90초, 즉 이 이슈가 보고한 그 구성입니다

scripts/test-daemon-systemd-restart.sh --yes --rounds 3 --bound 20

결과

stop bound   1min 30s

round 1   relay 부재 5.16s   ← server join이 5000ms에서 timeout
round 2   relay 부재 0.40s
round 3   relay 부재 0.39s
worst     5.16s
PASS

1라운드가 이 이슈의 답입니다

2일간 돌던 프로덕션 데몬(PID 371347)의 저널입니다.

11:47:35.712666  shutdown step 'headless agent termination' started
11:47:35.712683  shutdown step 'headless agent termination' finished in 0ms
11:47:35.712692  shutdown step 'agent session termination' started
11:47:35.712797  shutdown step 'agent session termination' finished in 0ms
11:47:35.712816  shutdown step 'stopped process resume' started
11:47:35.712871  shutdown step 'stopped process resume' finished in 0ms
11:47:35.712881  shutdown step 'server join' started
11:47:40.713478  shutdown step 'server join' timed out after 5000ms

이슈 본문의 추정은 이랬습니다.

종료는 agent sessions terminated 이후, server join 이전에서 멈춘 것으로 보인다.
monitor_handle.resume_all_stopped()가 바로 다음 단계다.

추정이 절반만 맞았습니다. resume_all_stopped(= stopped process resume)는 0ms에 끝납니다. 실제로 멈추는 것은 그 다음의 server join 입니다. 계측이 없던 당시에는 이 둘을 구분할 수 없었습니다.

그리고 그 hang이 5초에서 끊겼습니다. 경계가 없었다면 같은 hang이 TimeoutStopSec 90초를 다 먹었을 겁니다. 2·3라운드는 갓 뜬 데몬이라 server join이 250ms에 끝났습니다. 이 stall은 오래 돌던 데몬에서만 나타납니다.

acceptance

항목	상태
Linux systemd service restart E2E	충족
SIGTERM부터 새 relay socket LISTEN까지 실제 부재 시간 측정	충족 (5.16 / 0.40 / 0.39초)
반복 restart에서 상한 검증	충족 (3회)
90초 TimeoutStopSec 회귀 방지	충족 (기본 90초 구성에서 최악 5.16초)
stall injection으로 각 단계 timeout 이후 최종 종료 검증	미충족

마지막 항목은 결함 주입(TERMMESH_SHUTDOWN_STALL)이 아직 릴리즈되지 않아 0.222.0에서 불가능합니다. 스크립트는 릴리즈 빌드에 대고 --stall을 쓰면 무음으로 넘어가지 않고 실패로 보고합니다. 주입 안 된 재시작을 측정해놓고 "경계가 증명됐다"고 말하는 것을 막기 위해서입니다.

남은 것

server join이 왜 멈추는지는 여전히 모릅니다. 이번 측정은 "경계가 작동한다"를 증명했지 원인을 밝히지 않았습니다. 그 단계는 http_task, mobile_task, peer_task 셋을 join하는데 저널은 어느 것이 안 끝났는지 말해주지 않습니다.

재현 조건은 잡혔습니다. 오래 돌아 연결이 쌓인 데몬입니다. 이어서 파보겠습니다.

호스트 상태는 그대로입니다. Result=success, 버전 0.222.0 유지, manifest 6건과 live surface 3건 모두 보존, 바이너리 미교체.

[JINWOO-J]

마지막 acceptance 항목을 채웠습니다. 실제 systemd에서 stall 주입을 실행했습니다.

조건

root@jw-server를 0.228.0으로 올렸습니다. 주입은 릴리즈 빌드에 컴파일되지 않으므로(운영 환경에 남은 env var 하나가 모든 종료를 망치는 것을 막기 위해), v0.228.0 태그를 그 호스트에서 디버그 빌드해 잠시 올렸다가 되돌렸습니다. unit의 TimeoutStopSec=45는 그대로입니다.

--stall agents — 단계 timeout 후 teardown 계속

12:37:16.866416  shutdown step 'agent session termination' stalled by TERMMESH_SHUTDOWN_STALL
12:37:28.868363  shutdown step 'agent session termination' timed out after 12000ms

round 1: relay 부재 12.16s
round 2: relay 부재 12.18s

멈춘 단계가 자기 12초 제한에서 끝나고, teardown이 그 뒤로 계속 진행돼 프로세스가 정상 종료했습니다. 두 라운드 모두 재현됩니다.

--stall teardown — 런타임 밖 hard-exit

12:38:08.650664  teardown wedged for 90s by TERMMESH_SHUTDOWN_STALL
systemd[1]: term-meshd.service: Main process exited, code=exited, status=2/INVALIDARGUMENT

round 1: relay 부재 30.15s

90초를 자도록 만들었는데 30초 예산에서 끝났습니다. systemd가 종료 코드 2를 봤고, 45초 한계에 닿지 않아 SIGKILL로 escalate하지 않았습니다.

acceptance 정리

항목	상태
Linux systemd service restart E2E	충족
SIGTERM부터 새 relay socket LISTEN까지 실제 부재 시간 측정	충족
반복 restart에서 상한 검증	충족
90초 TimeoutStopSec 회귀 방지	충족
stall injection으로 각 단계 timeout 이후 최종 종료 검증	충족

이번에 측정 스크립트에서 결함 3개가 나왔습니다 (#477)

전부 제가 만든 것이고, 각각 실행을 잘못된 이유로 통과시켰습니다.

pipefail + grep -q — grep -q가 첫 매치에서 파이프를 닫아 journalctl이 SIGPIPE로 죽고, pipefail이 파이프라인을 실패로 만듭니다. 저널에 줄이 있는데도 없다고 판정했습니다. 거짓 통과를 막으려 넣은 가드가 거짓 실패를 내고 있었습니다.

준비 판정이 소켓 connect뿐이었던 것 — 두 리스너 모두 이후 startup 작업보다 먼저 bind하므로, 커널이 backlog로 연결을 받는 동안 데몬은 아직 서버를 started로 세지 않습니다. 그 창에서 재시작하면 required server failed during startup으로 빠져 agent 단계를 건너뜁니다. 주입한 stall이 실행조차 안 됐는데 0.46초에 PASS가 나왔습니다.

control ping만으로도 부족한 것 — peer 서버는 자기가 찍는 로그 줄 뒤에 started를 발행하므로 저널을 봐야 합니다. 지금은 셋 다 확인합니다.

남은 것

server join의 drain이 왜 오래 걸리는지는 여전히 미해결입니다. 앞선 코멘트에서 보고한 5초 stall의 원인 자체입니다. #474가 그 피해를 가뒀고(같은 호스트 A/B로 확인), 0.228.0에서도 같은 drain stall이 계속 관측됩니다.

0.222.0  supervised timed out after 5s → server join timed out 5000ms → 회수 건너뜀
0.228.0  supervised timed out after 2500ms → terminated 3 peer surface(s) → server join finished in 2602ms

즉 원인은 그대로이고 결과만 안전해졌습니다. 알아내려면 drain에 연결별 계측을 넣어 어느 task가 붙잡고 있는지 이름이 나오게 해야 합니다. 재현 조건은 "연결이 쌓인 데몬"으로 잡혔습니다.

이 이슈를 닫을지, 아니면 drain 원인 규명까지 열어 둘지는 판단이 필요합니다. acceptance는 전부 충족했습니다.

호스트는 릴리즈 바이너리로 복원했습니다. 0.228.0, 백업본과 바이트 동일, Result=success, drop-in 제거, 빌드 트리 삭제, manifest 6건과 live surface 3건 보존.

[JINWOO-J]

이 이슈는 열어 둡니다. acceptance는 다 채웠지만 원인이 남았습니다.

남은 것 하나

server join의 drain이 왜 연결 정리에 예산을 다 쓰는지. 0.222.0과 0.228.0 모두에서 관측되므로 원인은 그대로이고 결과만 안전해졌습니다.

0.222.0  supervised timed out after 5s     → server join timed out 5000ms → surface 회수 건너뜀
0.228.0  supervised timed out after 2500ms → terminated 3 peer surface(s) → join finished 2602ms

재현 조건: 연결이 쌓인 오래 돌던 데몬. 갓 뜬 데몬은 join이 250ms 안에 끝납니다.

다음 단계

shutdown_supervised에 연결별 계측을 넣어, drain이 예산을 다 썼을 때 어느 연결 task가 붙잡고 있었는지 저널에 이름이 남게 하는 것입니다. 지금은 "peer: supervised task shutdown timed out"까지만 나오고 그 안에 몇 개가 남았는지, 무엇이었는지 알 수 없습니다.

JoinSet이라 개별 task를 식별하려면 spawn 시점에 라벨을 붙여야 합니다. spawn_supervised가 라벨을 받아 두고, timeout 시 미완료 라벨을 나열하는 형태가 맞아 보입니다.

이미 들어간 것 (v0.228.0)

• 단계별 이름과 계측, 전체 30초 watchdog, 단계별 bounded timeout (d78dc4e5, v0.216.0)
• TimeoutStopSec=45 — unit이 배포판 기본 90초를 상속하던 것을 명시 (test(daemon): measure what a restart costs, and prove the bound holds #465)
• drain 예산을 바깥 한계보다 작게 (fix(daemon): leave a server's teardown room to finish after its drain #474) — 회수와 socket 제거가 실행되도록
• TERMMESH_SHUTDOWN_STALL 결함 주입과 릴리즈 빌드 게이트 (test(daemon): measure what a restart costs, and prove the bound holds #465, fix: honour cancellation, raise unread asset lists, keep injection out of release #469)
• 측정 스크립트 (test(daemon): measure what a restart costs, and prove the bound holds #465), 그 스크립트가 잘못된 이유로 통과하던 결함 3건 수정 (fix(test): make the systemd restart measurement able to fail honestly #477)