홈랩 WiFi 장애 자가복구 와치독

노트북 홈랩 서버의 유일한 네트워크 경로인 Intel Wireless 7260 카드가 PCIe 버스에서 소실되어 11시간 동안 외부 접속이 끊긴 장애의 원인 분석과, 재발을 막기 위한 절전·ASPM 비활성 설정 및 단계적 자가복구 와치독(재연결 → PCI 재스캔 → 재부팅) 구성을 정리함. 2026-10-19 기준.

1. 목차

• 목적
• 환경
• 장애 사례
• 원인 분석
• 대응 구성
• 와치독 동작
• 설치 절차
• 검증 방법
• 운영 포인트
• 한계와 후속
• 관련 문서

2. 목적

• WiFi 단일 경로 홈랩에서 무선 카드 장애가 곧 서비스 전면 중단으로 이어지는 구조를 완화.
• 장애 발생 시 사람이 콘솔 앞에 갈 때까지 기다리지 않고 수 분 안에 자동 복구.
• 같은 카드에서 반복된 펌웨어·버스 오류의 원인과 설정값을 기록해 재발 시 판단 근거로 사용.

3. 환경

4. 장애 사례

4.1 2026-10-19

• 증상: 서버 콘솔에 아래 메시지가 초당 수 회 반복, 외부에서 사이트·SSH 전부 불통.

iwlwifi 0000:01:00.0: Error sending STATISTICS_CMD: enqueue_hcmd failed: -5

• 시작: 02:15:32 커널 경고 Timeout waiting for hardware access (CSR_GP_CNTRL 0xffffffff) 와 __iwl_trans_pcie_grab_nic_access 스택 트레이스.
• 경과: 이후 enqueue_hcmd failed 약 6,800회 누적. 펌웨어 자동 재시작 없음. 13:29 수동 재부팅까지 약 11시간 중단.
• 복구: 콘솔에서 sudo reboot. 부팅 후 WiFi 자동 연결, 컨테이너 4개 자동 기동, 사이트 정상.

4.2 2026-08-13 (선례)

• 02:15:55 Hardware error detected. Restarting. + NMI_INTERRUPT_HOST. 펌웨어 자동 재시작으로 수 초 내 복구, 서비스 영향 없음.
• 두 건 모두 02:15 에 발생. 서버 크론에는 해당 시각 작업이 없어 공유기 예약 작업(재부팅·채널 변경)이나 전파 환경 변화가 의심 대상.

5. 원인 분석

• CSR_GP_CNTRL 0xffffffff: 레지스터 읽기 결과가 전부 1 — PCIe 장치가 버스에서 응답하지 않을 때의 전형적 값. 펌웨어 행(hang)이 아니라 장치 자체가 사라진 상태.
• enqueue_hcmd failed: -5(EIO): 드라이버가 사라진 장치에 명령을 넣으려다 실패한 후속 증상. 이 상태에서는 드라이버 재적재(modprobe -r iwlmvm iwlwifi)만으로는 PCI 재열거가 일어나지 않아 복구가 불확실함. 재부팅 또는 PCI remove/rescan 필요.
• 장애 당시 설정은 전부 기본값: iwlwifi power_save 켜짐, iwlmvm power_scheme=2(balanced), PCIe ASPM default. 7260 계열은 ASPM·절전 상태 전환 중 버스 드롭 보고가 많은 모델.
• 하드웨어 노후(2013년 출시)와 펌웨어 갱신 종료로 근본 수정은 기대하기 어려움 → 설정 완화 + 자동 복구로 대응.

6. 대응 구성

세 가지를 함께 적용함.

절전 비활성 설정 내용:

options iwlwifi power_save=0
options iwlmvm power_scheme=1

• power_scheme=1 = CAM(Continuously Aware Mode), 펌웨어가 항상 깨어 있음.
• pcie_aspm=off 는 전 PCIe 장치에 적용됨. 상시 전원 노트북이라 전력 손해는 무시 가능.
• 기존 OS 기본 파일 /etc/modprobe.d/iwlwifi.conf(모듈 제거 훅만 포함)는 손대지 않고 별도 파일로 추가.

7. 와치독 동작

root 크론 */5 * * * * 로 실행. 판정과 단계는 다음과 같음.

1. 부팅 후 10분 이내면 종료 (NetworkManager 연결 대기 구간 오탐 방지).
2. ip -4 route show default dev wlp1s0 로 게이트웨이를 얻고 ping -c 3 -W 2 -I wlp1s0 실행.
3. 성공: 실패 카운터 파일(/run/wifi-watchdog.fails)이 있으면 recovered 기록 후 삭제, 종료.
4. 실패: 카운터 +1, 로그에 FAIL #n, 인터페이스 존재 여부(hw_missing), 최근 커널 로그의 enqueue_hcmd failed 건수(hcmd_err) 기록.
5. 카운터별 조치:
   • 1회: nmcli device reconnect wlp1s0
   • 2회: nmcli device disconnect → /sys/bus/pci/devices/0000:01:00.0/remove → /sys/bus/pci/rescan → nmcli device connect
   • 3회 이상: 인터페이스가 사라졌거나 hcmd_err > 0 일 때만 reboot. 둘 다 아니면 "공유기 측 장애 추정" 로그만 남기고 재부팅하지 않음.

• 카운터는 /run 에 있어 재부팅 시 자동 초기화.
• 최악 경로(연속 3회 실패 → 재부팅)까지 약 15분. 장애 사례의 11시간을 15분 이내로 단축.
• 로그 /var/log/wifi-watchdog.log, 주 1회 로테이션 8세대 보관. 정상 상태에서는 아무 것도 기록하지 않음.

8. 설치 절차

설치 파일 묶음(설정 4개 + 설치 스크립트)을 서버 홈 디렉토리에 복사한 뒤 한 번 실행함. 스크립트는 멱등이며 재부팅은 하지 않음.

sudo bash install-iwlwifi-hardening.sh
sudo reboot

스크립트 수행 내용:

1. 복사된 파일의 CRLF 제거(Windows 에서 작성된 경우 대비).
2. iwlwifi-power.conf 설치 + update-initramfs -u.
3. GRUB 기본 커널 파라미터에 pcie_aspm=off 추가(없을 때만, 원본은 grub.bak-YYYYMMDD 백업) + update-grub.
4. 와치독 스크립트·크론·logrotate 설치, bash -n 문법 검사, 1회 즉시 실행.

• 와치독은 설치 즉시 동작. 절전·ASPM 은 재부팅 후 적용.
• 리포지토리에는 서버 절대경로 구조 그대로 미러를 보관(etc/·usr/ 하위)하여 재설치 시 디렉토리째 복사.

9. 검증 방법

재부팅 후 확인 명령과 기대값:

cat /sys/module/iwlwifi/parameters/power_save      # N
cat /sys/module/iwlmvm/parameters/power_scheme     # 1
grep -o pcie_aspm=off /proc/cmdline                 # pcie_aspm=off
journalctl -k -b --no-pager | grep -i aspm          # "PCIe ASPM is disabled"
cat /etc/cron.d/wifi-watchdog                       # */5 * * * * root ...
sudo tail /var/log/wifi-watchdog.log                # 정상이면 빈 파일
docker ps --format '{{.Names}} {{.Status}}'         # 4개 Up

• 2026-10-19 재부팅 후 위 항목 전부 기대값 확인.
• 강제 동작 테스트는 콘솔에서만: nmcli device disconnect wlp1s0 후 5분 대기 → 로그에 FAIL #1·step1 → 재연결되면 recovered. 원격 세션에서는 자신의 연결이 끊기므로 주의.

10. 운영 포인트

• 비root 계정의 dmesg 는 커널 로그 제한으로 출력이 없을 수 있음. 조사는 journalctl -k -b (이전 부팅은 -b -1) 사용. 와치독은 root 크론이라 dmesg 정상.
• 장애 조사 시 첫 오류 지점을 찾는 키워드: CSR_GP_CNTRL, Hardware error detected, Microcode SW error, Queue .* stuck. enqueue_hcmd failed 는 후속 증상이라 수천 건 반복되므로 첫 발생 시각만 의미 있음.
• 재부팅은 컨테이너에 안전: 4개 모두 unless-stopped 라 자동 기동. 재부팅 전 docker stop 으로 직접 내린 컨테이너만 수동 기동 필요.
• 커널 업데이트 후에도 pcie_aspm=off 는 GRUB 기본 파라미터라 유지됨. /etc/default/grub 를 다른 작업으로 덮어쓸 때만 재확인.
• 와치독이 재부팅까지 간 이력은 로그의 step3: reboot 줄로 확인. 반복되면 카드 교체 신호.

11. 한계와 후속

• 설정 완화는 발생 빈도를 낮출 뿐 하드웨어 드롭을 원천 차단하지 못함. 와치독이 실질적 안전망.
• 공유기 자체 장애·ISP 장애는 와치독 재부팅 조건에서 제외되므로 자동 복구 대상 아님.
• 02:15 반복 발생은 공유기 예약 작업 확인이 남은 과제.
• 근본 대안은 유선화: 노트북에 유선 포트가 없어 USB 이더넷 어댑터 추가가 현실적 선택. 적용 시 와치독의 인터페이스명·PCI 주소 상수 조정 또는 비활성 필요.

12. 관련 문서

• 홈랩 컨테이너 서비스 운영 ROAD MAP(17) · WORK LOG(18) — 홈랩 구성 전반.
• 배포 k8s → 컴포즈 전환 WORK LOG(28) — 현행 컴포즈 운영 구조와 컨테이너 재기동 정책.
• Certbot 인증서 발급 자동갱신(15) — 같은 서버의 크론 기반 운영 작업.