> For the complete documentation index, see [llms.txt](https://ia-cloud.gitbook.io/cloudia-manual/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ia-cloud.gitbook.io/cloudia-manual/administrator/monitoring/log-export.md).

# 로그 전송

로그 전송 페이지는 외부 로그 수신 서버를 등록하여 Cloud:iA 운영 로그를 syslog 프로토콜로 전송하도록 설정하는 화면입니다. Cloud:iA 백엔드 로그와 전체 노드의 호스트 에이전트 로그가 전송 대상이며, 수신 서버는 여러 대를 등록할 수 있습니다.

> 💡 **참고**
>
> * 외부 수신 서버와의 통신은 클러스터의 primary 노드가 대표로 수행합니다. 외부 방화벽에는 primary 노드 IP만 허용하면 됩니다.
> * 로그의 syslog 헤더에 원본 노드의 hostname이 보존되므로, 수신 서버에서 노드별로 로그를 구분할 수 있습니다.

## 로그 전송 목록

등록된 모든 로그 수신 서버를 확인하고 관리할 수 있습니다.

### 테이블 컬럼

| 컬럼명         | 설명                      |
| ----------- | ----------------------- |
| 로그 수신 서버 IP | 외부 로그 수신 서버의 IP 주소      |
| 포트          | 외부 로그 수신 서버의 포트         |
| 프로토콜        | 전송 프로토콜 (`tcp`/`udp`)   |
| 설명          | 수신 서버에 대한 설명 또는 용도      |
| 활성화 여부      | 로그 전송의 활성화 상태(활성화/비활성화) |
| 생성 일시       | 수신 서버가 등록된 시간           |

### 주요 기능

* `생성`: 생성 버튼 클릭 → 로그 전송 서버 등록 화면 이동
* `삭제`: 선택 후 삭제 버튼 클릭 (1개만 선택 가능)
* `활성화`: 비활성 상태의 항목 선택 후 활성화 버튼 클릭 (1개만 선택 가능)
* `비활성화`: 활성 상태의 항목 선택 후 비활성화 버튼 클릭 (1개만 선택 가능)

> 💡 **참고:** 등록된 수신 서버의 IP·포트·프로토콜은 수정할 수 없습니다. 변경이 필요하면 삭제 후 다시 등록합니다.

***

## 로그 전송 서버 등록

`생성` 버튼을 클릭하면 로그 전송 서버 등록 페이지로 이동합니다.

### 기본 정보

* **IP 주소**: 로그를 수신할 외부 서버의 IP 주소를 입력합니다.
* **포트**: 수신 서버의 포트를 입력합니다.
* **프로토콜**: 전송 프로토콜을 선택합니다 (`TCP`/`UDP`, 기본 `TCP`).
* **설명**: 수신 서버에 대한 설명을 입력합니다.
* **기존 로그 포함**: 토글을 켜면 등록 시점 이전에 쌓인 기존 로그 파일도 처음부터 전송합니다. 끄면(기본) 등록 시점 이후 로그만 전송합니다.

#### 입력 필드 유효성

| 필드        | 허용 값        | 검증 규칙                  | 비고                |
| --------- | ----------- | ---------------------- | ----------------- |
| **IP 주소** | IPv4 형식     | 형식 불일치 시 오류 표시         | **필수**            |
| **포트**    | 1 \~ 65535  | 범위 밖 정수 또는 정수가 아닌 값 불가 | **필수**            |
| **프로토콜**  | `TCP`/`UDP` | 선택 항목                  | **필수** (기본 `TCP`) |
| **설명**    | 최대 200자     | 초과 시 오류 표시             | 선택                |

> ⚠️ **주의:** 동일한 IP와 포트 조합은 중복 등록할 수 없습니다.

> 💡 **참고**
>
> * `기존 로그 포함`은 최초 등록 시점에 유효합니다. 이미 전송 중인 환경에 나중에 켜서 추가해도 과거 로그는 다시 전송되지 않습니다.
> * 압축(`.gz`)되거나 삭제된 과거 로그 파일은 `기존 로그 포함`을 켜도 전송되지 않습니다.
> * `UDP`는 프로토콜 특성상 전송 중 유실이 발생할 수 있습니다.

### 연결 테스트

등록 전에 `연결 테스트` 버튼으로 수신 서버 도달 여부를 확인할 수 있습니다.

* 검사는 실제 전송 주체인 primary 노드에서 수행되며, 결과 메시지가 버튼 옆에 표시됩니다.
* `TCP`는 연결 성립 여부로 판정합니다. `UDP`는 비연결형 프로토콜 특성상 도달을 보장하지 않습니다.
* 수신 서버에서 해당 포트가 리스닝 중이어야 합니다.
* 연결 테스트는 등록의 필수 조건이 아니며, IP·포트·프로토콜 값을 변경하면 이전 결과는 초기화됩니다.

입력을 완료하고 `등록` 버튼을 클릭하면 수신 서버가 등록되고 로그 전송이 시작됩니다.

***

## 활성화 / 비활성화

목록에서 항목을 선택하고 `활성화`/`비활성화` 버튼을 클릭하면 확인 창이 표시됩니다.

* **활성화**: 선택한 수신 서버로 로그 전송을 시작합니다. 비활성 상태였다가 다시 활성화하면 활성화 시점 이후의 로그부터 이어서 전송됩니다.
* **비활성화**: 선택한 수신 서버로의 로그 전송을 중지합니다.

> ⚠️ **주의:** 비활성화 기간에 발생한 로그는 해당 수신 서버로 전송되지 않으며, 다시 활성화해도 보충 전송되지 않습니다.

> 💡 **참고:** 다시 활성화해도 이미 전송된 로그가 중복 전송되지는 않습니다. `기존 로그 포함`으로 등록한 항목도 재활성화 시 과거 로그를 다시 보내지 않습니다.

***

## 삭제

목록에서 항목을 선택하고 `삭제` 버튼을 클릭하면 확인 창이 표시됩니다.

* 활성 상태의 로그 전송도 삭제할 수 있으며, 이 경우 전송을 중지한 뒤 삭제됩니다.

***

## 수신 서버 구축 가이드 (rsyslog)

아래는 외부 수신 서버(고객/운영 소유 장비)에 적용할 수 있는 rsyslog 기반 권장 구성입니다 (Rocky/RHEL 9, rsyslog 8.x 기준 검증).

### 포트/방화벽

* 관례 포트는 `514/tcp`, `514/udp`이지만, 등록 화면의 포트는 1\~65535 범위에서 자유롭게 정할 수 있습니다. 다른 포트를 쓰려면 아래 예시의 `514`를 그 포트로 바꿉니다. 둘 다(tcp/udp) 열어두면 등록 시 프로토콜 선택과 무관하게 동작합니다.
* inbound 허용 소스는 클러스터 **primary 노드 IP 1개**면 충분합니다 (relay 구조라 일반 노드 IP는 불필요).

  ```
  firewall-cmd --permanent --add-port=514/tcp --add-port=514/udp
  firewall-cmd --reload
  ```
* `514`는 SELinux 기본 syslog 포트라 별도 조치가 필요 없습니다. 다른 포트를 사용하는 경우 tcp/udp 각각에 대해 `semanage port -a -t syslogd_port_t -p tcp <포트>` / `semanage port -a -t syslogd_port_t -p udp <포트>`를 실행합니다(UDP를 쓸 계획이 없어도 둘 다 등록해 두는 편이 안전합니다). `semanage` 명령이 없다면 `dnf install -y policycoreutils-python-utils`로 먼저 설치합니다.

### rsyslog 수신 설정

1. 수신 설정 파일을 생성합니다: `/etc/rsyslog.d/00-cloudia-receive.conf`

   ```
   $umask 0022
   module(load="imtcp")
   input(type="imtcp" port="514")
   module(load="imudp")
   input(type="imudp" port="514")

   # Cloud:iA 로그를 노드별·소스별 파일로 분리 (권장 — 없으면 /var/log/messages에 혼재)
   template(name="cloudiaFile" type="string"
            string="/var/log/cloudia-export/%HOSTNAME%/%PROGRAMNAME%.log")
   if $programname == 'cloudia-backend' or $programname == 'host-agent' then {
     # root 외 계정도 읽도록 권한 완화. rsyslogd 기본 umask(0077)가 mode 를 깎으므로 상단 `$umask 0022`
     # 와 함께, action 파라미터 dirCreateMode/fileCreateMode 로 지정해야 0755/0644 로 생성된다.
     action(type="omfile" dynaFile="cloudiaFile" dirCreateMode="0755" fileCreateMode="0644")
     stop
   }
   ```
2. 문법 검증 후 rsyslog를 재시작합니다.

   ```
   rsyslogd -N1 && systemctl restart rsyslog
   ```
3. 로그 전송 페이지에서 수신 서버의 IP와 포트(`514`), 프로토콜로 등록하고, `연결 테스트`로 리스너 동작을 확인합니다.

### 수신 확인

```bash
ss -lntup | grep -w 514                      # 리스너 확인
tail -f /var/log/cloudia-export/*/*.log      # 실시간 유입 확인
ls -lR /var/log/cloudia-export/              # 노드별 도착 현황 (mtime)
```

### 수신측 운영 참고

* 수신 서버가 일시 다운되어도 송신측(primary)의 디스크 큐(대상별 최대 1GB)가 버퍼링하다가 복구 시 자동 재전송합니다 (TCP 등록 기준).
* 수신 로그의 보관 주기/용량 관리는 수신 서버의 logrotate로 별도 구성합니다.

### 참고: 수신 서버 준비 예시 (Cloud:iA VM)

수신 서버는 물리 서버·기존 가상화 인프라의 VM·클라우드 인스턴스 등 rsyslog(또는 동등한 syslog 수신기)를 올릴 수 있는 환경이면 무엇이든 가능합니다. 아래는 그중 한 예시로, 별도로 준비된 장비가 없을 때 Cloud:iA 안에 VM을 하나 만들어 위 rsyslog 설정을 그대로 적용하는 방법입니다.

* 클러스터에서 도달 가능한 것은 VM의 **공인 IP(Floating IP)** 뿐입니다. VM의 사설 IP는 로그 전송 등록/연결 테스트에 사용할 수 없으므로, Floating IP를 할당·연결한 뒤 그 주소를 등록합니다.
* VM의 보안 그룹 인바운드에서 위에서 정한 포트(`514` 등)와 확인용 `22/tcp`(SSH)를 허용해야 합니다.

***

## 변경 이력

* 2026-07-20: 최초 작성
* 2026-07-27: 수신 서버 구축 가이드에 Cloud:iA VM(+ Floating IP)을 활용하는 참고 방법 추가
* 2026-07-30: 활성화/비활성화에 재활성화 동작(활성화 시점 이후부터 재개, 중복 전송 없음) 설명 보강