// Notes

기술 노트 & 방법론

실무에서 지켜온 원칙과, 반복되지 않게 기록해둔 트러블슈팅 사례입니다.

// Principles

지식베이스 운영 원칙

개인 트러블슈팅 문서를 관리하며 지키는 5가지 원칙입니다.

01

로그를 먼저 본다

문제가 생기면 화면보다 로그 파일을 먼저 연다. 표시되는 상태와 실제 처리 결과는 다를 수 있다.

02

콘솔을 진실로 믿지 않는다

"정상"이라는 표시는 확인의 시작점일 뿐, 결론이 아니다. 항상 OS/에이전트 단에서 직접 재검증한다.

03

추측과 사실을 구분

기록할 때 검증된 사실과 아직 가설인 것을 명확히 나눈다. 나중에 스스로도 헷갈리지 않기 위해서다.

04

매뉴얼보다 실제가 우선

문서와 실제 환경이 다르면 실제 동작을 신뢰하되, 그 차이는 반드시 별도로 기록해둔다.

05

알아낸 즉시 기록

새로 알아낸 사실은 그 자리에서 바로 문서에 반영한다. 미루면 결국 잊혀지거나 다시 삽질한다.

+

미해결도 남긴다

원인을 못 찾은 문제도 "미해결" 목록에 그대로 남겨서, 같은 삽질을 반복하지 않도록 관리한다.

// Sample Notes

트러블슈팅 기록 예시

실무 중 겪은 문제를 일반적인 sysadmin 상황으로 정리한 예시입니다.

SYMPTOM

신규 Windows 서버에 WinRM 원격 접속이 안 됨

CAUSE

기본 설정만으로는 도메인 밖(워크그룹) 환경에서 신뢰 관계가 없어 PowerShell Remoting이 거부된다.

FIX 
# 접속하는 쪽(클라이언트)
Set-Item WSMan:\localhost\Client\TrustedHosts -Value "*" -Force

# 접속받는 쪽(대상 서버)
New-ItemProperty -Path HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System `
  -Name LocalAccountTokenFilterPolicy -Value 1 -PropertyType DWord -Force
Enable-PSRemoting -Force
# 방화벽 인바운드 규칙(WINRM-HTTP-In-TCP)의 RemoteAddress를 Any로 허용
SYMPTOM

Windows에서 만든 스크립트를 SSH로 실행하면 첫 줄이 깨짐

CAUSE

bash: line 1: su: command not found — 원인은 문법 오류가 아니라 파일 맨 앞에 붙은 UTF-8 BOM.

FIX 
# BOM 제거 후 실행
sed '1s/^\xef\xbb\xbf//' script.sh | bash -s

# 근본 대책: 스크립트는 UTF-8(BOM 없음)으로 저장
SYMPTOM

한글 PDF 매뉴얼을 텍스트로 추출하면 전부 공백으로 깨짐

CAUSE

일반적인 PDF 텍스트 추출 도구가 특정 한글 인코딩 폰트를 제대로 처리하지 못한다.

FIX

텍스트 추출을 포기하고 페이지를 이미지로 렌더링해서 읽는다. Windows라면 별도 프로그램 설치 없이 Windows.Data.Pdf API로 페이지별 PNG 렌더링이 가능하다.

SYMPTOM

리눅스 서버 로그를 열면 한글이 깨져 보임

CAUSE

로그가 UTF-8이 아닌 CP949(EUC-KR 계열)로 기록되는 환경이 여전히 많다.

FIX 
iconv -f CP949 -t UTF-8 로그파일.txt