---
title: "서버 등록하기"
description: "Alpamon 에이전트를 설치해 클라우드나 온프레미스 서버를 Alpacon에 등록합니다. 등록 전에 지원 플랫폼과 필수 요구사항을 확인하고 설치 후 서버가 온라인으로 표시되는지 살펴보세요. 연결 오류가 나면 상태를 점검하고 이 페이지의 해결 절차에 따라 다시 연결할 수 있습니다."
---

> Full documentation index: https://docs.alpacax.com/llms.ko.txt

# 서버 등록하기

Alpacon에 서버를 등록하여 브라우저에서 관리할 수 있습니다.

## 사용자 서버란?

사용자 서버는 개인이나 팀이 직접 운영하는 서버를 말합니다. Alpacon은 두 유형을 모두 등록하고 관리합니다.

- **클라우드 기반 서버**(예: AWS, GCP, Azure)
- **온프레미스 서버**(사용자가 직접 관리하는 서버)

클라우드와 온프레미스를 함께 쓰는 하이브리드 환경에서도 **Alpacon의 일관된 UI/UX로 모든 서버를 똑같이 관리**합니다.

**주요 이점:**

- 모든 서버 유형에 대한 통합 관리 인터페이스
- 서버 위치와 무관한 일관된 경험
- 클라우드와 온프레미스 구분 불필요
- 중앙 집중식 제어 및 모니터링

## 등록 절차

서버 등록은 세 단계로 진행됩니다.

1. **등록 방식 선택**: 등록 방법을 고릅니다
2. **정보 입력**: 서버 세부 정보를 입력합니다(방식마다 다릅니다)
3. **설치 가이드**: 생성된 설치 스크립트나 명령어를 실행합니다

### 등록 방식

| 방식 | 적합한 경우 |
| --- | --- |
| 토큰으로 등록 | CLI 명령어로 서버를 하나 또는 여러 대 등록 |
| Ansible | 대량 등록 및 구성 관리 워크플로우 |

---

### 토큰으로 등록

[서버 등록 토큰](/use/servers/register/tokens/)과 생성된 CLI 명령어를 사용하여 서버를 등록합니다. 같은 토큰으로 서버를 한 대 또는 여러 대 등록할 수 있어, 단건과 대량 등록 모두에 적합한 방식입니다.

#### 1단계: 등록 방식 선택

1. 좌측 사이드바에서 **Servers**를 클릭합니다
2. 우측 상단의 **서버 등록** 버튼을 클릭합니다
3. **토큰으로 등록**을 선택합니다

#### 2단계: 서버 정보 입력

- **서버의 OS는 무엇인가요?** (필수): 서버 OS 선택. **Debian 계열**, **Redhat 계열**, **SUSE 계열**(openSUSE, SLES), **macOS**, **Windows** 중에서 고릅니다. **SUSE 계열**은 이 방식에서만 고를 수 있고 [Ansible](#ansible)에서는 고를 수 없습니다.
- **Alpacon에서 이 서버를 어떤 이름으로 표시할까요?** (선택): 최대 20자. 서버 이름의 접두어로 사용됩니다. 지정하지 않으면 서버의 호스트 이름이 사용됩니다.
- **서버 등록 토큰** (선택): 드롭다운에서 기존 토큰을 선택하거나 즉석에서 생성

등록된 서버에 어떤 사용자 그룹이 접근할 수 있는지는 이 폼이 아니라 등록 토큰이 결정합니다. 서버는 토큰의 허용 그룹(토큰 생성 시 설정)을 그대로 상속합니다. [서버 등록 토큰](/use/servers/register/tokens/)을 참고하세요.

#### 3단계: 에이전트 설치

토큰 기반 CLI 설치 명령어가 생성되어 화면에 표시됩니다.

1. 생성된 명령어를 복사합니다
2. 대상 서버에서 실행합니다
3. 설치가 끝날 때까지 기다립니다
4. 서버 목록에서 상태가 **온라인**으로 표시되는지 확인합니다

openSUSE나 SLES 서버는 2단계에서 **SUSE 계열**을 선택하고 생성된 명령어를 실행하세요. 이 명령어는 필요할 때 Alpamon 패키지 저장소를 추가하고 갱신한 다음 `zypper`로 Alpamon을 설치합니다. sudo와 MFA가 켜져 있으면 `alpamon-pam`도 설치합니다. RHEL 설치 명령어를 대신 사용하지 마세요. 등록을 위해 sudoers를 별도로 수정할 필요는 없습니다.

에이전트가 연결된 뒤 서버의 플랫폼이 `rhel`로 표시될 수 있습니다. openSUSE와 SLES에서 정상적인 표시이며, 패키지 작업에는 계속 `zypper`가 사용됩니다.

---

### Ansible

`alpacax.alpacon` 컬렉션의 `register` 모듈을 사용해 Ansible playbook으로 여러 서버에 Alpamon 에이전트를 설치하고 등록합니다. 대량 등록이나 이미 Ansible로 서버를 관리하는 팀에 적합합니다. 모듈은 **멱등성**이 있어 playbook을 다시 실행해도 이미 등록된 호스트는 안전하게 건너뜁니다.

#### 시작하기 전에

- **컨트롤 노드**: Python 3.11+와 Ansible 2.15+(`pip install ansible`), 대상 서버에 대한 SSH 키 기반 접근.
- [서버 등록 토큰](/use/servers/register/tokens/). 토큰이 등록된 서버에 접근할 수 있는 그룹을 결정합니다.
- 컬렉션 설치:

```bash
ansible-galaxy collection install alpacax.alpacon --upgrade
```

#### 1단계: 등록 방식 선택

1. 좌측 사이드바에서 **Servers**를 클릭합니다
2. 우측 상단의 **서버 등록** 버튼을 클릭합니다
3. **Ansible**을 선택한 뒤 **플랫폼**을 고릅니다(필요하면 서버 이름과 등록 토큰도 지정합니다)

선택한 내용에 맞춰 Alpacon이 인벤토리와 실행 명령어가 포함된 가이드를 생성해 줍니다.

#### 2단계: 인벤토리 구성

작업 디렉터리에 `inventory.ini`를 만듭니다.

```ini
[targets]
YOUR_IP ansible_user=YOUR_USER  # ansible_ssh_private_key_file=/path/to/YOUR_KEY.pem
```

`YOUR_IP`는 대상 서버의 IP나 호스트 이름으로, `YOUR_USER`는 SSH 사용자로 바꿉니다. **Windows** 대상은 `ansible_connection=ssh ansible_shell_type=powershell`을 추가하세요.

계속하기 전에 연결을 확인합니다. `SUCCESS`가 표시되어야 합니다.

```bash
ansible -i inventory.ini targets -m ping
```

**Windows** 대상에서는 `ping`이 동작하지 않습니다(대상에 Python이 필요). 대신 `ansible.windows` 컬렉션의 `win_ping`을 사용하세요: `ansible -i inventory.ini targets -m ansible.windows.win_ping`.

#### 3단계: 등록

두 가지 방법 중 하나를 선택합니다.

**옵션 A: 번들 playbook** (단건 설치, 작성할 playbook 없음):

```bash
ansible-playbook -i inventory.ini alpacax.alpacon.register \
  -e alpacon_url=https://your-workspace.ap1.alpacon.io \
  -e registration_token=YOUR_REGISTRATION_TOKEN_KEY \
  -e platform=debian
```

**옵션 B: 커스텀 playbook** (재사용 가능, 기존 자동화에 통합). `playbook.yml`로 저장하세요.

```yaml
- hosts: targets
  become: true
  tasks:
    - alpacax.alpacon.register:
        alpacon_url: "https://your-workspace.ap1.alpacon.io"
        registration_token: "{{ registration_token }}"
        platform: "debian"
      no_log: true
```

```bash
ansible-playbook -i inventory.ini playbook.yml \
  -e registration_token=YOUR_REGISTRATION_TOKEN_KEY
```

> **보안:** 위 예시는 간결함을 위해 토큰을 `-e registration_token=...`로 전달하는데, 이렇게 하면 셸 히스토리와 프로세스 목록에 토큰이 노출될 수 있습니다. 단건 실행이 아니라면 토큰을 Ansible Vault에 보관하고 명령줄 대신 변수로 참조하세요.

#### 모듈 파라미터

- `alpacon_url`(필수): Alpacon 워크스페이스 URL.
- `registration_token`(필수): 등록 토큰 키. 평문 대신 Ansible Vault에 보관하세요.
- `platform`(필수): `debian`, `rhel`, `darwin`, `windows`.
- `server_name`(선택): 지정하지 않으면 대상의 호스트 이름을 사용합니다.
- `package_proxy`(선택): 패키지 설치에 사용할 HTTP 프록시 URL.
- `allow_sudo_with_mfa`(선택, Linux 전용): [sudo with MFA](/use/work-sessions/terminal/sudo-with-mfa/)를 위해 `alpamon-pam` 패키지도 설치합니다.

#### 플랫폼별 참고

- **Linux**(`debian` = Debian/Ubuntu, `rhel` = RHEL/Rocky/Alma/Fedora): `become: true`로 실행합니다. 대상 사용자에게 root 또는 비밀번호 없는 sudo 권한이 필요합니다.
- **openSUSE와 SLES**: Ansible 등록 안내에는 선택지가 없습니다. [등록 토큰](#토큰으로-등록)으로 등록하세요. Ansible 안내에서 `rhel`을 선택해도 SUSE용 설치 명령어가 생성되지는 않습니다.
- **macOS**(`darwin`): `become: true`를 설정하지 **마세요**. Homebrew는 root 실행을 거부합니다. 대상에 Homebrew가 설치돼 있어야 하며(Alpamon은 `alpacax/alpacon` tap으로 배포), `package_proxy`와 `allow_sudo_with_mfa`는 적용되지 않습니다. 컨트롤 노드가 macOS면 `ansible-playbook` 실행 전에 `OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES`를 export하세요.
- **Windows**: `become: true`를 설정하지 **마세요**. 접속 사용자가 이미 Administrator여야 합니다. PowerShell 5.1+, TLS 1.2, `github.com`으로의 아웃바운드 HTTPS가 필요합니다.

---

## 지원 플랫폼

지원 운영체제, 버전, 아키텍처 및 기능 범위는 [지원 플랫폼](/reference/platforms/)에서 확인하세요. Windows 설정과 복구 방법은 [Windows 서버](/reference/platforms/windows/)를 참고하세요.

### 플랫폼별 기능 범위

등록 전에 [플랫폼별 기능](/reference/platforms/)을 확인하세요.

## 필수 요구사항

**서버:**

- 지원되는 운영체제 및 아키텍처 ([지원 플랫폼](#지원-플랫폼) 참고)
- 설치를 위한 관리자 권한 (Linux/macOS는 root/sudo, Windows는 관리자 권한 PowerShell)
- 인터넷 연결

**네트워크:**

- 아웃바운드 HTTPS 연결 가능 (포트 443)
- Alpacon API 서버 접근 가능

## 문제 해결

**연결 상태가 "오프라인"으로 표시되는 경우**: 플랫폼에 맞는 명령으로 에이전트 상태 확인, 재시작, 로그 점검을 수행하세요.

**Linux (systemd)**

```bash
sudo systemctl status alpamon
sudo systemctl restart alpamon
sudo journalctl -u alpamon -n 50
```

**macOS (launchd)**

```bash
sudo launchctl print system/com.alpacax.alpamon
sudo launchctl kickstart -k system/com.alpacax.alpamon
tail -n 50 /var/log/alpamon/alpamon.log
```

**Windows (Service Control Manager)**

관리자 권한 PowerShell에서:

```powershell
sc.exe query alpamon
Restart-Service alpamon
Get-Content "$env:ProgramData\alpamon\log\alpamon.log" -Tail 50
```

Windows에서 `install.ps1` 스크립트는 다시 실행해도 안전하지만, `alpamon register` 자체는 이미 등록된 호스트에서는 `config file already exists`로 실패합니다. 재등록하거나 복구하려면 Websh가 아닌 서버에서 직접 `alpamon register --force`(또는 `alpamon unregister` 후 `alpamon register`)를 실행하세요. [등록 복구](/use/servers/troubleshooting/#재등록-및-복구)를 참고하세요.

**설치 실패 시:**

- 관리자 권한 확인 (Linux/macOS는 sudo, Windows는 관리자 권한 PowerShell)
- 인터넷 연결 확인
- 지원 플랫폼인지 확인

## 보안 고려사항

**에이전트 통신:**

- 모든 통신은 TLS 암호화
- 서버에서 Alpacon으로의 아웃바운드 연결만 필요
- 인바운드 포트 오픈 불필요

**인증:**

- 각 서버는 고유한 토큰으로 인증
- 토큰은 설치 시에만 사용되며 서버에 안전하게 저장

## 다음 단계

서버 등록 후:

- [서버 접속하기](/use/servers/connect/)
- [서버 접근 제어하기](/use/servers/groups/)
- [서버 모니터링](/use/servers/monitor/)

Source: https://docs.alpacax.com/ko/use/servers/register/