Alpamon 설치

서버에 Alpacon 에이전트(Alpamon)를 설치하고 워크스페이스에 연결하는 방법을 알아봅니다.

사전 요구사항

Alpacon을 설치하기 전에 다음을 확인하세요:

Alpacon 워크스페이스: 없다면 데모를 신청해 AlpacaX 팀과 함께 설정하거나 관리자에게 초대를 요청하세요
서버 요구사항:
- 지원되는 OS (지원 플랫폼 참조)
- 설치를 위한 root 또는 sudo 접근 권한
- 아웃바운드 HTTPS 연결 (포트 443)
- 150MB 여유 디스크 공간
- 128MB 사용 가능한 RAM

지원 플랫폼

운영체제와 아키텍처는 지원 플랫폼에서 확인하세요.

플랫폼별 기능 범위

플랫폼에 따라 다른 기능은 Windows 기능 표를 참고하세요.

빠른 설치

Alpamon을 설치하고 등록하는 권장 방법입니다.

1단계: 워크스페이스에서 서버 등록 준비

Alpacon 워크스페이스에 로그인
Servers → 서버 등록으로 이동한 뒤 토큰으로 등록 선택
서버의 OS는 무엇인가요?에서 플랫폼을 선택하고, 필요하면 서버 이름을 지정한 다음 등록 토큰을 선택합니다. 접근 그룹은 이 양식에서 설정하지 않고 토큰에서 상속됩니다.

전체 등록 절차(Ansible 포함)는 서버 등록하기를 참고하세요.

2단계: 생성된 명령으로 설치

워크스페이스에서 생성된 명령을 복사하여 서버에서 실행합니다. 워크스페이스는 선택한 플랫폼에 맞춰 명령을 자동 생성합니다.

Linux / macOS: 터미널에 붙여넣습니다.

bash

# The command will look similar to this:
curl https://your-workspace.ap1.alpacon.io/api/servers/installers/YOUR_UNIQUE_ID/ | sudo -EH bash

Windows: 관리자 권한 PowerShell(관리자 권한으로 실행)에 붙여넣습니다. 생성된 명령은 GitHub Releases에서 에이전트를 내려받고 체크섬을 검증한 뒤 alpamon.exe register를 실행합니다. 동일한 수동 단계는 Windows를 참고하세요.

명령은 어느 경우든 다음을 수행합니다:

Alpamon 에이전트 설치
워크스페이스에 서버 등록
에이전트를 서비스로 시작

참고

Linux와 macOS에서 sudo -EH는 환경 변수(예: 프록시 설정)를 유지하고 설치 과정의 HOME을 설정합니다.

3단계: 설치 확인

워크스페이스에서 서버 목록에 서버가 온라인 상태로 표시되는지 확인합니다. 이제 터미널을 통해 접근할 수 있습니다.

수동 설치 (고급)

참고

대부분의 사용자에게는 워크스페이스에서 생성된 설치 명령 사용을 권장합니다 (빠른 설치 참조). 수동 설치 시 별도 등록이 필요합니다.

Linux 패키지는 packagecloud.io에서 호스팅됩니다. macOS는 Homebrew tap을 사용하고, Windows는 GitHub Releases에 게시된 릴리스 아카이브를 사용합니다.

Linux

방법 1: 레포지토리 설치 (권장)

이 방법을 사용하면 시스템 패키지 관리자를 통한 자동 업데이트가 가능합니다.

1단계: Alpacon에서 환경변수 가져오기

설치 전에 Alpacon 워크스페이스에서 등록 자격 증명을 가져와야 합니다.

방법 A: Alpacon 웹 UI 사용

Alpacon 워크스페이스에 로그인
Servers → 서버 등록으로 이동
새 서버 항목 생성
설치 안내에서 환경변수 복사: ALPACON_URL, PLUGIN_ID, PLUGIN_KEY

방법 B: Alpacon CLI 사용

bash

# CLI로 서버 생성 (대화형 프롬프트)
alpacon server create
 
# 생성 후 환경변수가 포함된 설치 안내가 표시됩니다
# ALPACON_URL, PLUGIN_ID, PLUGIN_KEY 값을 복사하세요

2단계: 환경변수 설정

대상 서버에서 자격 증명을 export합니다.

bash

export ALPACON_URL="https://your-workspace.ap1.alpacon.io"
export PLUGIN_ID="your-plugin-id"
export PLUGIN_KEY="your-plugin-key"

중요

설치 중에 이 변수들이 유지되도록 반드시 export로 내보내세요. sudo -EH의 -EH 플래그가 환경변수를 보존하고 설치 과정의 HOME을 설정합니다.

3단계: Alpamon 설치

DEB 기반 시스템 (Ubuntu/Debian):

bash

# 레포지토리 및 GPG 키 추가 (환경변수 보존)
curl -s https://packagecloud.io/install/repositories/alpacax/alpamon/script.deb.sh?any=true | sudo -EH bash
 
# Alpamon 설치 (환경변수를 사용하여 자동 등록)
sudo -EH apt-get install -y alpamon
 
# 서비스 시작 및 활성화
sudo systemctl start alpamon
sudo systemctl enable alpamon

RPM 기반 시스템 (RHEL/Rocky/Alma/Fedora):

bash

# 레포지토리 추가 (환경변수 보존)
curl -s https://packagecloud.io/install/repositories/alpacax/alpamon/script.rpm.sh?any=true | sudo -EH bash
 
# Alpamon 설치 (환경변수를 사용하여 자동 등록)
sudo -EH yum install -y alpamon
 
# 서비스 시작 및 활성화
sudo systemctl start alpamon
sudo systemctl enable alpamon

SUSE 기반 시스템 (openSUSE/SLES):

bash

# zypper에 저장소 추가 (alpamon 저장소가 이미 있으면 건너뜀)
sudo -EH zypper lr alpamon >/dev/null 2>&1 || \
  sudo -EH zypper --non-interactive addrepo -f \
  'https://packagecloud.io/alpacax/alpamon/rpm_any/rpm_any/$basearch' alpamon
sudo -EH zypper --non-interactive --gpg-auto-import-keys refresh alpamon
 
# Alpamon 설치 (자동 등록을 위해 환경 변수 사용)
sudo -EH zypper --non-interactive install alpamon
 
# 서비스 시작 및 활성화
sudo systemctl start alpamon
sudo systemctl enable alpamon

openSUSE와 SLES에서는 RPM 기반 시스템용 script.rpm.sh 명령을 쓰지 마세요. 이 명령이 만드는 저장소는 zypper가 쓰지 못합니다.

참고

워크스페이스에 sudo with MFA가 활성화되어 있으면 설치 명령에 alpamon-pam을 추가하여 PAM 모듈도 함께 설치하세요. 예를 들어 sudo -EH apt-get install -y alpamon alpamon-pam(RHEL 계열은 yum, openSUSE와 SLES는 zypper 사용)입니다. openSUSE와 SLES에는 alpamon-pam 1.1.5 이상이 필요합니다(PAM 및 sudo 문제 참고). 워크스페이스에서 생성된 명령은 이를 자동으로 추가합니다.

방법 2: 직접 패키지 다운로드

특정 패키지 버전을 직접 다운로드하여 설치합니다. 이 방법도 자동 등록을 위해 환경변수가 필요합니다.

1단계: 환경변수 가져오기 및 설정

방법 1과 동일한 단계로 ALPACON_URL, PLUGIN_ID, PLUGIN_KEY를 가져와서 export합니다.

bash

export ALPACON_URL="https://your-workspace.ap1.alpacon.io"
export PLUGIN_ID="your-plugin-id"
export PLUGIN_KEY="your-plugin-key"

2단계: 다운로드 및 설치

DEB 기반 시스템 (Ubuntu/Debian):

bash

# Download the package. Filenames follow alpamon_<version>_linux_<arch>.deb.
# Check the exact filename on the package page: https://packagecloud.io/alpacax/alpamon
wget "https://packagecloud.io/alpacax/alpamon/packages/ubuntu/focal/alpamon_<version>_linux_amd64.deb/download.deb" -O alpamon.deb
 
# 패키지 설치 (환경변수 보존)
sudo -EH dpkg -i alpamon.deb
 
# 누락된 종속성 설치
sudo -EH apt-get install -f -y
 
# 서비스 시작
sudo systemctl start alpamon
sudo systemctl enable alpamon

RPM 기반 시스템 (RHEL/Rocky/Alma/Fedora):

bash

# Download the package. Filenames follow alpamon-<version>-1.linux.<arch>.rpm.
# Check the exact filename on the package page: https://packagecloud.io/alpacax/alpamon
wget "https://packagecloud.io/alpacax/alpamon/packages/el/8/alpamon-<version>-1.linux.x86_64.rpm/download.rpm" -O alpamon.rpm
 
# 패키지 설치 (환경변수 보존)
sudo -EH rpm -i alpamon.rpm
 
# 서비스 시작
sudo systemctl start alpamon
sudo systemctl enable alpamon

모든 패키지 찾아보기: packagecloud.io/alpacax/alpamon에서 여러 OS 버전과 아키텍처별로 제공되는 모든 패키지를 확인하세요.

참고

설치 중에 환경변수가 올바르게 설정되면 에이전트가 자동으로 등록됩니다. 그렇지 않으면 수동 등록을 진행하세요.

macOS

Homebrew로 Alpamon을 설치한 뒤 alpamon register를 실행하면 설정 파일이 작성되고 launchd 서비스가 시작됩니다. 아래 $(brew --prefix) 형식은 Apple Silicon(/opt/homebrew/bin)과 Intel(/usr/local/bin) Mac 모두에서 동작합니다. Apple Silicon에서는 sudo가 Homebrew 바이너리를 찾지 못할 수 있으므로 전체 경로를 사용합니다.

bash

brew tap alpacax/alpacon
brew install alpamon
sudo "$(brew --prefix)/bin/alpamon" register \
  --url https://your-workspace.ap1.alpacon.io \
  --token YOUR_REGISTRATION_TOKEN

brew install은 다시 실행해도 안전하지만, alpamon register 자체는 이미 등록된 호스트에서는 config file already exists로 실패합니다. 재등록하거나 복구하려면 서버에서 직접 alpamon register --force(또는 alpamon unregister 후 alpamon register)를 실행하세요. 등록 복구를 참고하세요.

Windows

관리자 권한 PowerShell(관리자 권한으로 실행)을 열고 아래 두 방법 중 하나를 선택하세요. 두 방법 모두 alpamon.exe register가 에이전트를 C:\Program Files\alpamon\에 설치하고, 부팅 시 자동으로 시작되는 Windows 서비스로 등록한 뒤 서비스를 시작합니다. install.ps1 스크립트는 다시 실행해도 안전하지만, alpamon.exe register 자체는 이미 등록된 호스트에서는 config file already exists로 실패합니다. 재등록하거나 복구하려면 Websh가 아닌 서버에서 직접 alpamon.exe register --force(또는 alpamon.exe unregister 후 alpamon.exe register)를 실행하세요. 등록 복구를 참고하세요.

방법 1: 수동 설치

GitHub Releases에서 alpamon-X.Y.Z-windows-amd64.zip을 다운로드합니다. 바이너리가 서명되어 있지 않아 Windows가 SmartScreen으로 차단할 수 있으므로, 압축을 풀기 전에 ZIP 파일의 차단을 해제하세요: Unblock-File .\alpamon-X.Y.Z-windows-amd64.zip. 그런 다음 압축을 풉니다.
압축을 푼 폴더에서 관리자 권한 PowerShell을 통해 실행:

powershell

.\alpamon.exe register `
    --url https://your-workspace.ap1.alpacon.io `
    --token YOUR_REGISTRATION_TOKEN

방법 2: `install.ps1` 자동 설치

cloud-init, EC2 UserData, Packer, Azure Custom Script Extension에 권장됩니다. 스크립트는 릴리스 아카이브를 다운로드하고, 릴리스와 함께 게시된 체크섬으로 다운로드 무결성을 검증한 뒤 압축을 풀고 alpamon register를 실행합니다.

파일 다운로드 후 실행 (권장: 설치 스크립트가 디스크에 남아 감사가 가능합니다):

powershell

$env:ALPAMON_URL   = "https://your-workspace.ap1.alpacon.io"
$env:ALPAMON_TOKEN = "YOUR_REGISTRATION_TOKEN"
$installer = Join-Path $env:TEMP 'alpamon-install.ps1'
Invoke-WebRequest -UseBasicParsing `
    -Uri 'https://raw.githubusercontent.com/alpacax/alpamon/main/scripts/install.ps1' `
    -OutFile $installer
& powershell -ExecutionPolicy Bypass -File $installer

파이프 iex 형식 (명령이 짧지만 나중에 검토할 스크립트 파일은 남지 않습니다):

powershell

$env:ALPAMON_URL   = "https://your-workspace.ap1.alpacon.io"
$env:ALPAMON_TOKEN = "YOUR_REGISTRATION_TOKEN"
iwr https://raw.githubusercontent.com/alpacax/alpamon/main/scripts/install.ps1 -UseB | iex

고급: 수동 등록

Alpamon을 수동으로 설치한 경우(워크스페이스에서 생성된 설치 명령을 사용하지 않고)에는 별도로 등록할 수 있습니다:

등록 정보 받기

Alpacon 워크스페이스에 로그인
Servers → 서버 등록으로 이동한 뒤 토큰으로 등록 선택
서버 등록 토큰 필드에서 새 토큰 만들기를 클릭하고 표시되는 키를 복사합니다. 키는 한 번만 표시되므로, 기존 서버 등록 토큰을 쓰려면 만들 때 저장해 둔 키를 사용하세요.

서버 등록

서버에서 등록 명령 실행:

bash

sudo alpamon register \
  --url https://your-workspace.ap1.alpacon.io \
  --token YOUR_REGISTRATION_TOKEN \
  --name "production-web-01" \
  --tag env=prod --tag role=web

옵션:

--url: Alpacon 서버 URL (필수)
--token: 서버 등록 토큰 키 (필수)
--name: 서버 이름 (선택사항, 기본값: 호스트네임)
--platform: 플랫폼 타입 debian, rhel, darwin, windows (선택사항, 자동 감지)
--ssl-verify: SSL 인증서 검증 활성화 (기본값: true)
--ca-cert: CA 인증서 파일 경로 (선택사항)
--tag: key=value 형식의 서버 태그 (선택사항, 반복 지정 가능)
--no-cloud-probe: 클라우드 호스트에서 클라우드 제공자 메타데이터 자동 감지 건너뛰기 (선택사항)
--force: 막힌 서버 복구. 새로 등록한 뒤, 새 등록이 커밋되면 이전 등록을 회수합니다(이전 등록은 새 등록이 성공할 때까지 유지). alpamon v2.3.0 이상 필요.
--no-rollback: 등록이 실패해도 부분 상태를 정리하지 않고 그대로 둡니다(디버그 전용, 일반 사용 비권장). alpamon v2.3.0 이상 필요.

등록 확인

플랫폼에 맞는 명령으로 에이전트 상태를 확인합니다.

Linux

bash

sudo systemctl status alpamon
sudo journalctl -u alpamon -f

macOS

bash

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

Windows

powershell

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

워크스페이스에서:

Servers 페이지로 이동
서버가 “Connected”로 표시되어야 함
서버를 클릭하여 터미널에 접근

다음 단계

설치를 마쳤다면 다음을 진행하세요.

접근 제어 구성 - 역할 및 권한 설정
Websh를 통한 연결 - 브라우저를 통해 서버에 접근
활동 검토 - 세션·명령·승인 결정 감사
CI/CD와 통합 - 배포 자동화

도움이 필요하신가요?

문제 해결 가이드 확인
FAQ 방문
Discord 커뮤니티 참여
이메일 지원: support@alpacax.com

Alpamon 설치

사전 요구사항#

지원 플랫폼#

플랫폼별 기능 범위#

빠른 설치#

1단계: 워크스페이스에서 서버 등록 준비#

2단계: 생성된 명령으로 설치#

3단계: 설치 확인#

수동 설치 (고급)#

Linux#

방법 1: 레포지토리 설치 (권장)#

1단계: Alpacon에서 환경변수 가져오기

2단계: 환경변수 설정

3단계: Alpamon 설치

방법 2: 직접 패키지 다운로드#

1단계: 환경변수 가져오기 및 설정

2단계: 다운로드 및 설치

macOS#

Windows#

방법 1: 수동 설치#

방법 2: install.ps1 자동 설치#

고급: 수동 등록#

등록 정보 받기#

서버 등록#

등록 확인#

관련 작업#

다음 단계#

도움이 필요하신가요?#

사전 요구사항

지원 플랫폼

플랫폼별 기능 범위

빠른 설치

1단계: 워크스페이스에서 서버 등록 준비

2단계: 생성된 명령으로 설치

3단계: 설치 확인

수동 설치 (고급)

Linux

방법 1: 레포지토리 설치 (권장)

방법 2: 직접 패키지 다운로드

macOS

Windows

방법 1: 수동 설치

방법 2: `install.ps1` 자동 설치

고급: 수동 등록

등록 정보 받기

서버 등록

등록 확인

관련 작업

다음 단계

도움이 필요하신가요?