에이전트 문제

Alpamon 에이전트 관련 문제 해결 가이드입니다.

에이전트 설치 실패

서버 OS 계열을 잘못 선택한 경우

에이전트 설치 시 서버의 OS 계열을 잘못 선택하면 설치가 실패할 수 있습니다.

기본 설치 스크립트는 OS 종류와 무관하게 동일한 스크립트를 사용하므로 대부분의 경우 문제없이 설치됩니다. 하지만 에이전트를 수동으로 설치할 경우, OS 계열에 따라 설치 스크립트가 달라지므로 잘못된 OS를 선택하면 설치에 실패합니다.

해결 방법:

  1. 서버의 실제 OS 계열 확인:

    • Debian 계열: Ubuntu, Debian 등
    • Red Hat 계열: RHEL, CentOS, Fedora, Amazon/Rocky/Oracle Linux 등
    • macOS: macOS 11 이상
    • Windows: Windows Server 2019 / 2022 / 2025, Windows 10 1803+, Windows 11

  2. 서버 등록 페이지에서 서버 등록 시 올바른 OS 계열 선택

  3. 수동 설치 스크립트 사용 시, 선택한 OS 계열에 맞는 스크립트로 에이전트를 설치:

    • Debian 계열: apt-get install -y alpamon 명령이 포함된 스크립트
    • Red Hat 계열: yum install -y alpamon 명령이 포함된 스크립트
    • macOS: brew install alpamon 명령이 포함된 스크립트
    • Windows: alpamon.exe register를 실행하는 PowerShell 스크립트

  4. 잘못된 OS 계열로 서버를 등록한 경우 서버를 삭제한 후 올바른 OS 계열로 재등록

워크스페이스를 이전한 경우

다른 워크스페이스에서 사용하던 서버를 에이전트 삭제 과정 없이 신규 워크스페이스에 등록한 경우, 에이전트는 기존 워크스페이스에 계속 연동된 상태로 동작할 수 있습니다. 이 경우 신규 워크스페이스에서는 서버 연결이 불가능합니다.

해결 방법:

  1. 기존 워크스페이스에서 에이전트 자동 삭제 선택 후 서버 삭제 (기존 에이전트 서버에서 제거)

  2. 기존 워크스페이스 접근 불가 시 서버 제거하기 참고하여 수동 에이전트 삭제

  3. 신규 워크스페이스에서 서버 등록 및 에이전트 설치 새로 수행

재등록 및 복구

등록이 막혔거나 중간에 실패한 호스트를 복구하는 명령입니다. Websh가 아닌 서버에서 직접(로컬 콘솔, RDP, 클라우드 시리얼 콘솔), 그리고 alpamon v2.3.0 이상에서 실행하세요. 구버전 에이전트에는 register --force와 unregister가 없으므로(일반 alpamon register는 그대로 사용 가능), 에이전트를 수동으로 제거하고 Servers 페이지에서 서버를 삭제한 뒤 다시 등록하세요.

alpamon register가 config file already exists에서 멈춤

이미 등록된 호스트라서 alpamon register가 재등록을 거부합니다. alpamon register --force로 한 번에 재등록하세요. 새로 등록한 뒤 새 등록이 성공하면 이전 등록을 회수합니다. 또는 alpamon unregister를 먼저 실행한 뒤 alpamon register를 실행해도 됩니다.

등록이 중간에 실패함

등록이 일부 상태를 만든 뒤 실패하면 호스트가 반쯤 등록된 상태로 남을 수 있습니다. alpamon register --force로 깨끗이 재등록하면 남은 등록이 회수됩니다.

원인 분석을 위해 상태 보존

기본적으로 alpamon register는 실패하면 그 실행에서 만든 상태를 롤백합니다. 문제 분석을 위해 부분 상태를 남기려면 --no-rollback을 추가하세요(예: alpamon register --force --no-rollback). 디버그 전용이며 부분 상태를 남깁니다.

Windows 에이전트 문제

서비스가 시작되지 않음

alpamon Windows 서비스가 시작되지 않으면 먼저 서비스 상태와 에이전트 로그를 확인하세요.

sc.exe query alpamon
Get-Content "$env:ProgramData\alpamon\log\alpamon.log" -Tail 100

에이전트 로그에 나타나지 않는 Service Control Manager 수준 오류(예: 바이너리 누락 또는 읽기 불가)는 이벤트 뷰어의 Windows 로그 → 시스템에서 Service Control Manager 항목을, 응용 프로그램 및 서비스 로그에서 alpamon 항목을 확인하세요.

alpamon register 또는 서비스 작업 시 접근 거부

alpamon register와 서비스 제어 명령(sc.exe, Restart-Service)은 모두 관리자 권한이 필요합니다. 관리자 권한 PowerShell(관리자 권한으로 실행)에서 다시 실행하세요. alpamon register는 C:\Program Files\alpamon\에 바이너리를 복사할 수 없을 때 권한 상승 안내를 출력합니다.

재설치 중 ERROR_SHARING_VIOLATION이 표시되면 실행 중인 서비스가 기존 alpamon.exe를 점유하고 있는 경우입니다. 먼저 서비스를 중지하고 다시 시도하세요:

sc.exe stop alpamon
.\alpamon.exe register --url https://your-workspace.ap1.alpacon.io --token YOUR_API_TOKEN

등록 자체가 막혔거나 중간에 실패했다면 재등록 및 복구를 참고하세요.

Websh에서 PowerShell error 8009001d 발생

초기 Windows 빌드에서 발생하던 TLS 관련 Websh 핸드셰이크 오류로, 이후 Alpamon 릴리스에서 수정되었습니다. 최신 릴리스로 설치 프로그램을 다시 실행해 업그레이드한 뒤 다시 시도하세요.

Windows에서 WebFTP가 사용자 홈을 넘어 C:\Windows\System32\... 등도 표시됨

의도된 동작입니다. Windows의 WebFTP는 특정 사용자 홈 디렉터리로 제한되지 않으며, 에이전트가 접근할 수 있는 호스트의 모든 경로를 탐색하고 읽고 쓸 수 있습니다(C:\Windows\System32 같은 시스템 디렉터리 포함). 접근 범위는 서버의 사용자별 홈 경계가 아니라 Alpacon 역할 및 권한과 연결 허용 사용자 목록으로 제어됩니다. WebFTP 접근 권한은 신중하게 부여하고, 민감한 위치에 접근할 수 있는 사용자는 Alpacon 역할로 제한하세요. 접근 제어 방식은 WebFTP 권한을 참고하세요.

macOS 에이전트 문제

서비스가 시작되지 않음

launchd 서비스 상태와 에이전트 로그를 확인하세요:

sudo launchctl print system/com.alpacax.alpamon
tail -n 100 /var/log/alpamon/alpamon.log

launchd 수준의 오류(예: 실행 파일을 찾을 수 없거나 plist가 유효하지 않은 경우)는 Console.app에서 com.alpacax.alpamon으로 필터링하면 launchd 자체 오류 메시지를 확인할 수 있습니다.

서비스 재시작

sudo launchctl kickstart -k system/com.alpacax.alpamon

에이전트가 보호된 디렉터리를 읽을 수 없음

macOS는 시스템 보호 경로(메일, 메시지, Time Machine, 일부 ~/Library 등)에 접근하는 프로세스에 대해 Full Disk Access를 요구합니다. 에이전트가 해당 위치를 읽을 때 권한 오류를 보고하면 시스템 설정 → 개인정보 보호 및 보안 → 전체 디스크 접근 권한에서 alpamon 바이너리에 권한을 부여한 뒤 서비스를 재시작하세요.

바이너리 위치는 Mac 종류에 따라 다릅니다:

  • Apple Silicon: /opt/homebrew/bin/alpamon
  • Intel: /usr/local/bin/alpamon

에이전트 업그레이드 문제

Alpacon은 두 가지 방법으로 Alpamon 에이전트를 최신 상태로 유지합니다.

  • 자동: 워크스페이스 설정에서 자동 에이전트 업그레이드가 켜져 있으면(기본값), 등록된 에이전트가 알아서 최신 버전으로 업그레이드됩니다.
  • 수동: CLI에서 alpacon agent upgrade SERVER로 특정 서버를 업그레이드한 뒤, alpacon events로 진행 상황을 확인합니다.

업그레이드 중에는 에이전트가 새 버전을 받아 적용한 뒤 자동으로 재시작합니다. 서버가 잠깐 오프라인으로 표시됐다가 다시 연결될 수 있습니다. 업데이트를 적용하지 못하면 에이전트는 이전 버전을 그대로 유지합니다. 업데이트 전달 방식은 플랫폼에 따라 다릅니다.

  • Linux(Debian/Ubuntu, RHEL/CentOS): 시스템 패키지 매니저(apt/yum)를 통해 Alpacon 패키지 저장소에서 받습니다.
  • macOS: GitHub Releases에서 내려받습니다.
  • Windows: 명령 기반 업그레이드를 사용할 수 없습니다. 최신 릴리스로 설치 프로그램을 다시 실행해 업데이트하세요(Windows 설치 참고).

업그레이드가 시작되지 않을 때

  • 서버가 온라인인지 확인하세요. 오프라인 상태의 에이전트는 업그레이드 요청을 받을 수 없습니다.
  • alpacon agent upgrade SERVER를 실행하고 alpacon events로 결과를 확인하세요.
  • 자동 업그레이드를 사용한다면 워크스페이스 설정에서 자동 에이전트 업그레이드가 켜져 있는지 확인하세요.

업그레이드가 실패하거나 버전이 그대로일 때

  • 연결 확인: 모든 플랫폼은 api.github.com에서 최신 버전을 확인하므로, 서버가 api.github.com으로의 아웃바운드 HTTPS를 허용해야 합니다. Linux에서는 이후 apt/yum으로 업그레이드하므로, 서버가 Alpacon 패키지 저장소에 직접 또는 워크스페이스 패키지 프록시 설정을 통해 접근할 수 있어야 합니다. macOS에서는 에이전트가 github.com에서 릴리스를 직접 내려받습니다. Windows는 명령 기반 업그레이드가 없으며, 설치 프로그램을 다시 실행해 업데이트합니다.
  • 에이전트 로그에서 원인을 확인한 뒤 업그레이드를 다시 시도하세요.
    • Linux: sudo journalctl -u alpamon -n 100
    • macOS: tail -n 100 /var/log/alpamon/alpamon.log
  • 업그레이드가 실패하면 에이전트는 이전 버전을 그대로 유지합니다. 원인(대개 네트워크나 패키지 저장소 접근)을 해결한 뒤 다시 시도하세요.

현재 버전 확인

서버 상세 페이지에서 실행 중인 에이전트 버전을 확인할 수 있습니다. 언제든 업그레이드를 다시 실행해도 되며, 이미 최신이면 아무것도 바뀌지 않습니다.

최종 수정: