# Panther 로그 포워더 (베타)

## 개요

{% hint style="info" %}
Panther Log Forwarder는 Panther 버전 1.121부터 오픈 베타이며, 모든 고객이 사용할 수 있습니다. 버그 보고와 기능 요청은 Panther 지원 팀에 공유해 주세요.
{% endhint %}

Panther Log Forwarder는 온프레미스 인프라의 로그를 Panther로 전달하기 위한 경량 도구입니다. 파일 또는 syslog에서 로그를 수집하고 HTTP 소스 또는 S3 버킷을 통해 Panther로 전송합니다.

## 다운로드 링크

플랫폼에 맞는 최신 릴리스를 다운로드하세요:

| 플랫폼             | 다운로드 링크                                                                                                                                                                    | 체크섬                                                                                                                                           |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Linux (x86\_64) | [panther-log-forwarder\_linux\_amd64.tar.gz](https://panther-community-us-east-1.s3.us-east-1.amazonaws.com/log-forwarder/latest/panther-log-forwarder_linux_amd64.tar.gz) | [SHA256](https://panther-community-us-east-1.s3.us-east-1.amazonaws.com/log-forwarder/latest/panther-log-forwarder_linux_amd64.tar.gz.sha256) |
| Linux (ARM64)   | [panther-log-forwarder\_linux\_arm64.tar.gz](https://panther-community-us-east-1.s3.us-east-1.amazonaws.com/log-forwarder/latest/panther-log-forwarder_linux_arm64.tar.gz) | [SHA256](https://panther-community-us-east-1.s3.us-east-1.amazonaws.com/log-forwarder/latest/panther-log-forwarder_linux_arm64.tar.gz.sha256) |

## 시작하기

다음 단계를 따라 로그 포워더를 설치하고 몇 분 안에 로그 전송을 시작하세요. 이는 기본 구성으로 파일에서 Panther의 HTTP 소스로 로그를 전송하는 예시입니다. S3 버킷으로 로그를 전송하는 방법과 더 많은 구성 옵션은 아래를 참조하세요.

### 사전 요구 사항

* systemd가 있는 Linux (Ubuntu 20.04+, Debian 11+, RHEL 8+, Rocky Linux 8+)
* sudo/root 권한
* Panther Console의 HTTP 소스 URL 및 Bearer 토큰(참조 [HTTP 전송 문서](/ko/data-onboarding/data-transports/http.md))

### 1단계: 설치

```bash
# 다운로드 (x86_64 — ARM64의 경우 "amd64"를 "arm64"로 바꾸세요)
wget https://panther-community-us-east-1.s3.us-east-1.amazonaws.com/log-forwarder/latest/panther-log-forwarder_linux_amd64.tar.gz

# 압축 해제 및 설치
tar -xzf panther-log-forwarder_linux_amd64.tar.gz
cd panther-log-forwarder
sudo ./install.sh
```

{% hint style="info" %}
**선택 사항: 설치 전에 체크섬 확인**

```bash
wget https://panther-community-us-east-1.s3.us-east-1.amazonaws.com/log-forwarder/latest/panther-log-forwarder_linux_amd64.tar.gz.sha256
sha256sum -c panther-log-forwarder_linux_amd64.tar.gz.sha256
```

{% endhint %}

### 2단계: 포워더 구성

다음 위치에 YAML 파일을 생성하세요 `/etc/panther-log-forwarder/forwarders.d/` 그리고 다음 내용을 붙여넣으세요. `url` Run Panther AI `token` 값을 HTTP 로그 소스의 값으로 바꾸세요.

```yaml
forwarders:
  my_app_logs:
    input:
      type: file
      path: /var/log/testapp
    output:
      type: http
      url: https://logs.your-instance.runpanther.net/http/YOUR_SOURCE_ID
      auth:
        type: bearer
        token: YOUR_BEARER_TOKEN
```

### 3단계: 검증 및 시작

```bash
# 구성을 검증합니다
sudo panther-log-forwarder validate

# Panther 연결을 테스트합니다
sudo panther-log-forwarder check-connectivity

# 서비스를 시작합니다
sudo systemctl start panther-log-forwarder
sudo systemctl enable panther-log-forwarder

# 실행 중인지 확인합니다
sudo panther-log-forwarder status
```

{% hint style="success" %}
로그는 몇 분 내에 Panther의 Data Explorer에 표시되어야 합니다.
{% endhint %}

***

## 명령어

| 명령어                                                         | 설명                   |
| ----------------------------------------------------------- | -------------------- |
| `panther-log-forwarder validate`                            | 구성 문법 검증             |
| `panther-log-forwarder check-connectivity`                  | 모든 대상에 대한 연결 테스트     |
| `panther-log-forwarder check-connectivity --forwarder NAME` | 특정 포워더 테스트           |
| `panther-log-forwarder start`                               | 포그라운드에서 실행(디버깅용)     |
| `panther-log-forwarder status`                              | 상태, 메트릭, 각 포워더 통계 표시 |
| `panther-log-forwarder --version`                           | 버전 표시                |

프로덕션 환경에서는 systemd를 사용하세요: `sudo systemctl start panther-log-forwarder`

***

## 구성 참고

로그 포워더는 두 가지 유형의 구성 파일을 사용합니다:

1. **전역 설정** in `/etc/panther-log-forwarder/panther.conf` — 설치 중에 적절한 기본값으로 자동 생성됨
2. **포워더 정의** in `/etc/panther-log-forwarder/forwarders.d/*.yaml` — 수집할 로그와 전송 위치를 정의하기 위해 사용자가 생성

### 전역 구성

설치 프로그램이 다음을 생성합니다 `/etc/panther-log-forwarder/panther.conf` 기본값으로. 기본값을 변경해야 할 때만 편집하세요:

```yaml
# /etc/panther-log-forwarder/panther.conf
default_source_buffer_size: 3GB   # 포워더당 디스크 버퍼(기본값: 3GB)
log_level: info                   # debug, info, warn, error (기본값: info)
log_format: text                  # text 또는 json (기본값: text)
```

### 포워더 구성

각 포워더는 다음 아래에 고유한 이름으로 추가됩니다 `forwarders` 그리고 다음을 가집니다 `input` (무엇을 수집할지) 및 `output` (어디로 전송할지) 섹션을 가집니다.

포워더 이름은 문자로 시작해야 하며, 영숫자, 밑줄, 하이픈만 포함할 수 있고, 길이는 1\~64자여야 합니다.

포워더를 여러 파일로 나누어 구성할 수도 있고 하나의 파일에 모두 넣을 수도 있습니다 — 어떤 `.yaml` 파일이든 `forwarders.d/` 에 있으면 로드됩니다.

### 입력 유형

#### 파일 입력

glob 패턴을 사용해 로그 파일을 추적합니다:

```yaml
input:
  type: file
  path: /var/log/app/*.log       # glob 지원: *.log, **/*.log
  excludes: ["*.gz", "*.zip"]    # 선택 사항: 제외할 패턴
  read_from: end                 # 선택 사항: "end"(기본값) 또는 "beginning"
```

| 필드          | 필수  | 기본값   | 설명                                                                              |
| ----------- | --- | ----- | ------------------------------------------------------------------------------- |
| `type`      | 예   | —     | 다음이어야 함 `파일을`                                                                   |
| `path`      | 예   | —     | 파일 경로 또는 glob 패턴                                                                |
| `excludes`  | 아니요 | —     | 제외할 glob 패턴 배열                                                                  |
| `read_from` | 아니요 | `end` | `end` = 새 줄만; `beginning` = 기존 내용 읽기                                            |
| `format`    | 아니요 | —     | 콘텐츠 형식 힌트. 다음으로 설정 `syslog` syslog 형식 파일을 추적할 때(다음과 함께 사용 `parse: json`, 아래 참조) |
| `parse`     | 아니요 | —     | 다음으로 설정: `json` syslog 줄을 구조화된 JSON으로 파싱하려면(다음을 요구함 `format: syslog`)           |

{% hint style="warning" %}
사용 시 `read_from: beginning` 파일에 있는 기존 로그 줄을 모두 전송합니다. 큰 파일의 경우 상당한 시간과 디스크 버퍼 공간이 필요할 수 있습니다.
{% endhint %}

**참고:**

* 줄바꿈으로 구분된 로그만 지원됩니다(한 줄당 하나의 로그 항목)
* 현재는 여러 줄로 된 로그를 지원하지 않습니다
* 시작 시 로그 포워더는 파일 경로 접근 가능 여부를 검증하고 시작 전에 권한 오류를 보고합니다

#### Syslog 입력

네트워크를 통해 syslog 메시지를 수신합니다:

```yaml
input:
  type: syslog
  mode: tcp              # "tcp" 또는 "udp"
  address: 0.0.0.0:1514  # 수신 주소
```

| 필드        | 필수  | 설명                                            |
| --------- | --- | --------------------------------------------- |
| `type`    | 예   | 다음이어야 함 `syslog`                              |
| `mode`    | 예   | `tcp` 또는 `udp`                                |
| `address` | 예   | 수신할 호스트와 포트                                   |
| `parse`   | 아니요 | 다음으로 설정: `json` syslog 메시지를 구조화된 JSON으로 파싱하려면 |

**참고:**

* 메시지는 원시 형식으로 Panther로 전송됩니다. 메시지가 RFC 3164 또는 RFC 5424 형식을 따른다면, Panther에 내장된 해당 syslog 스키마([`Syslog.RFC5424`](https://docs.panther.com/ko/data-onboarding/pages/e2ef2ec852b6071be2513315909591bc2771c13e#syslog.rfc5424)/[`Syslog.RFC3164`](https://docs.panther.com/ko/data-onboarding/pages/e2ef2ec852b6071be2513315909591bc2771c13e#syslog.rfc3164))를 사용하여 적절한 파싱과 분류를 수행할 수 있습니다.
* 다음을 사용하여 `parse: json` 메시지를 파싱된 json으로 Panther 소스로 전송하려면 사용합니다. 파싱은 최선의 노력 방식이며 RFC 준수 형식뿐만 아니라 가장 일반적인 syslog 형식을 대부분 처리합니다.

### 출력 유형

#### HTTP 출력

Panther HTTP 소스로 로그를 전송합니다:

```yaml
output:
  type: http
  url: https://logs.your-instance.runpanther.net/http/SOURCE_ID
  auth:
    type: bearer
    token: ptl-your-bearer-token
  buffer_size: 10GB  # 선택 사항: 전역 기본값 재정의
```

| 필드            | 필수  | 기본값    | 설명                                           |
| ------------- | --- | ------ | -------------------------------------------- |
| `type`        | 아니요 | `http` | 출력 유형(HTTP의 경우 생략 가능)                        |
| `url`         | 예   | —      | Panther HTTP 소스 URL                          |
| `auth`        | 예   | —      | 인증 구성(참조 [자격 증명 관리](#credential-management)) |
| `buffer_size` | 아니요 | `3GB`  | 포워더별 디스크 버퍼 크기 재정의                           |

#### S3 출력

Amazon S3 버킷으로 로그를 전송합니다 — 구성에 AWS 키가 필요하지 않습니다.

```yaml
output:
  type: s3
  bucket: my-log-bucket
  region: us-east-1
  key_prefix: "custom/prefix/%Y/%m/%d/"  # 선택 사항
```

| 필드            | 필수  | 기본값                               | 설명                                       |
| ------------- | --- | --------------------------------- | ---------------------------------------- |
| `type`        | 예   | —                                 | 다음이어야 함 `s3`                             |
| `bucket`      | 예   | —                                 | S3 버킷 이름                                 |
| `리전`          | 예   | —                                 | AWS 리전(예: `us-east-1`)                   |
| `key_prefix`  | 아니요 | `logs/{forwarder_name}/%Y/%m/%d/` | S3 키 접두사(strftime 토큰 지원, 다음으로 끝나야 함 `/`) |
| `buffer_size` | 아니요 | `3GB`                             | 포워더별 디스크 버퍼 크기 재정의                       |

**참고:**

* 인증: **IAM 인스턴스 프로필** (권장) 또는 **환경 변수** (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`). 파일 기반 자격 증명(`~/.aws/credentials`)은 서비스가 홈 디렉터리에 접근할 수 없으므로 지원되지 않습니다.
* 사용되는 IAM ID에는 다음 권한이 있어야 합니다 `s3:PutObject` Run Panther AI `s3:HeadBucket` 대상 버킷에 대한 권한
* 로그는 업로드 전에 gzip으로 압축됩니다
* 배치: 10MB 또는 60초 중 먼저 도래하는 것

### 자격 증명 관리

HTTP 출력에는 Bearer 토큰이 필요합니다. 제공하는 방법은 두 가지입니다:

#### 평문 토큰

```yaml
output:
  auth:
    type: bearer
    token: ptl-your-bearer-token
```

포워더 파일은 다음으로 보호됩니다 `0640` 권한과 `root:panther-log-forwarder` 소유권 — root만 쓸 수 있고, 에이전트 서비스만 읽을 수 있습니다.

#### 환경 변수

다음을 사용하여 `${ENV_VAR}` 환경 변수를 참조하는 문법:

```yaml
output:
  auth:
    type: bearer
    token: "${PANTHER_TOKEN}"
```

systemd, Docker Compose, Kubernetes Secrets 등에서 변수를 설정하세요.

### 디스크 버퍼링

각 포워더에는 네트워크 중단 시 데이터 손실을 방지하기 위한 자체 디스크 버퍼(기본값: 3GB)가 있습니다. 로그는 전달될 수 있을 때까지 디스크에 저장됩니다.

버퍼가 가득 차면:

* **파일 입력** — 포워더는 버퍼 공간이 확보될 때까지 읽기를 차단하고 중지합니다(데이터 손실은 없지만 로그 파일이 커질 수 있음)
* **Syslog 입력** — 포워더는 새로 들어오는 메시지를 가장 최근 것부터 폐기합니다(메모리 문제는 방지하지만 일부 로그가 손실될 수 있음)

버퍼 크기는 다음에서 전역적으로 구성할 수 있습니다 `panther.conf` 또는 포워더별로 다음을 사용하여 `buffer_size` 출력 섹션에서.

기본값 3GB는 대부분의 배포에 충분합니다. 데이터 손실이 없도록 고용량 소스의 경우 버퍼 크기를 늘리는 것을 고려하세요.

### Syslog 파싱

기본적으로 syslog 메시지는 원시 텍스트로 전달됩니다. 입력에 `parse: json` 를 추가하면 syslog 메시지가 구조화된 JSON으로 파싱되며 다음과 같은 필드가 포함됩니다 `timestamp`, `hostname`, `appname`, `심각도`및 `message`.

이것은 두 가지 입력 유형 모두에서 작동합니다:

* **네트워크 syslog** (`type: syslog` + `parse: json`) — 내장 syslog 파싱 사용
* **파일 syslog** (`type: file` + `format: syslog` + `parse: json`) — 각 줄을 syslog 메시지로 파싱

#### 파싱이 있는 네트워크 syslog

```yaml
forwarders:
  parsed_syslog:
    input:
      type: syslog
      mode: tcp
      address: 0.0.0.0:1514
      parse: json
    output:
      url: https://logs.your-instance.runpanther.net/http/SOURCE_ID
      auth:
        type: bearer
        token: ptl-your-token
```

#### 파싱이 있는 파일 syslog

다음을 사용하여 `format: syslog` Run Panther AI `parse: json` 파일에 파싱해야 하는 syslog 형식 줄이 포함되어 있음을 나타내기 위해 입력에 다음을 사용하세요:

```yaml
forwarders:
  os_syslog:
    input:
      type: file
      path: /var/log/syslog
      format: syslog
      parse: json
    output:
      url: https://logs.your-instance.runpanther.net/http/SOURCE_ID
      auth:
        type: bearer
        token: ptl-your-token
```

{% hint style="info" %}
`parse: json` syslog 컨텍스트가 필요합니다 — 다음 중 하나 `input.type: syslog` 또는 `input.format: syslog`. 일반 파일 입력과는 함께 사용할 수 없습니다.
{% endhint %}

{% hint style="warning" %}
다음 경우 `parse: json` 가 활성화되면 파싱은 최선의 노력 방식이지만 RFC 3164 / RFC 5424를 포함한 대부분의 일반적인 syslog 형식을 처리합니다. 파싱에 실패한 줄은 폐기됩니다.
{% endhint %}

***

## 더 많은 예시

### Syslog 서버

```yaml
# /etc/panther-log-forwarder/forwarders.d/syslog.yaml
forwarders:
  my_syslog:
    input:
      type: syslog
      mode: tcp
      address: 0.0.0.0:1514
    output:
      type: http
      url: https://logs.your-instance.runpanther.net/http/SOURCE_ID
      auth:
        type: bearer
        token: ptl-your-token
```

### 제외 항목이 있는 여러 파일

```yaml
# /etc/panther-log-forwarder/forwarders.d/app.yaml
forwarders:
  app_logs:
    input:
      type: file
      path: /var/log/myapp/*.log
      excludes: ["*.gz", "*.old"]
    output:
      type: http
      url: https://logs.your-instance.runpanther.net/http/SOURCE_ID
      auth:
        type: bearer
        token: ptl-your-token
```

### 하나의 파일에 여러 포워더

```yaml
# /etc/panther-log-forwarder/forwarders.d/all-logs.yaml
forwarders:
  auth_logs:
    input:
      type: file
      path: /var/log/auth.log
    output:
      type: http
      url: https://logs.your-instance.runpanther.net/http/source1
      auth:
        type: bearer
        token: ptl-token-auth

  syslog_server:
    input:
      type: syslog
      mode: tcp
      address: 0.0.0.0:1514
    output:
      type: http
      url: https://logs.your-instance.runpanther.net/http/source2
      auth:
        type: bearer
        token: ptl-token-syslog
```

### JSON 파싱이 있는 Syslog to S3

```yaml
# /etc/panther-log-forwarder/forwarders.d/syslog-s3.yaml
forwarders:
  syslog_to_s3:
    input:
      type: syslog
      mode: udp
      address: 0.0.0.0:514
      parse: json
    output:
      type: s3
      bucket: my-log-bucket
      region: us-east-1
```

### S3 출력

```yaml
# /etc/panther-log-forwarder/forwarders.d/s3.yaml
forwarders:
  s3_archive:
    input:
      type: file
      path: /var/log/app/*.log
    output:
      type: s3
      bucket: my-log-bucket
      region: us-east-1
```

***

## 문제 해결

### 로그 확인

문제 해결 시 확인해야 할 로그 파일은 두 개입니다:

* **`/var/log/panther-log-forwarder/log-forwarder.log`** — 시작 실패, 구성 오류, 연결 문제 등 포워더 서비스 자체의 문제를 확인하세요.
* **`/var/log/panther-log-forwarder/vector.log`** — 로그 수집 문제, 파싱 오류, 전송 실패 등 데이터 파이프라인의 문제를 확인하세요.

```bash
# 포워더 서비스 로그
sudo tail -f /var/log/panther-log-forwarder/log-forwarder.log

# 데이터 파이프라인 로그
sudo tail -f /var/log/panther-log-forwarder/vector.log
```

### 로그 포워더가 시작되지 않음

```bash
sudo panther-log-forwarder status
```

일반적인 원인:

* **구성 오류** — 실행 `sudo panther-log-forwarder validate`
* **권한 문제** — 확인 `/etc/panther-log-forwarder/forwarders.d/` 가 다음을 가지고 있는지 `0750` 권한을 설정합니다
* **파일 접근 오류** — 로그 포워더는 시작 시 파일 경로를 확인합니다. 경로가 존재하고 다음 사용자에게 읽기 가능한지 확인하세요 `panther-log-forwarder` 사용자
* **포트 충돌** — syslog 입력의 경우 수신 포트가 사용 가능한지 확인하세요

### Panther에 로그가 표시되지 않음

```bash
sudo panther-log-forwarder check-connectivity
sudo panther-log-forwarder status
```

일반적인 원인:

* **잘못된 Bearer 토큰** — 토큰이 Panther Console과 일치하는지 확인하세요
* **네트워크 문제** — Panther 엔드포인트에 대한 HTTPS 연결을 테스트하세요
* **잘못된 URL** — Panther Console의 URL을 다시 확인하세요
* **파일 경로 문제** — 경로가 존재하고 읽을 수 있는지 확인하세요
* **S3 권한** — S3 출력의 경우 IAM 권한이 PutObject 및 HeadBucket을 허용하는지 확인하세요

### 구성 오류

```bash
sudo panther-log-forwarder validate
```

일반적인 문제:

* YAML 문법 오류(들여쓰기, 따옴표)
* 필수 필드 누락(`type` 입력에서, `url`/`auth` HTTP의 경우, `bucket`/`리전` S3의 경우)
* 잘못된 입력 유형(다음이어야 함 `파일을` 또는 `syslog`)
* 잘못된 출력 유형(다음이어야 함 `http` 또는 `s3`)
* 잘못된 포워더 이름(문자로 시작해야 하며, 영숫자/밑줄/하이픈만 허용)

***

## 작업

### 새 포워더 추가

1. Panther Console에서 새 소스(HTTP 또는 S3)를 생성하세요.
2. 다음 위치에 새 YAML 파일을 추가하세요 `/etc/panther-log-forwarder/forwarders.d/`.
3. 검증: `sudo panther-log-forwarder validate`
4. 재시작: `sudo systemctl restart panther-log-forwarder`

### 구성 업데이트

1. 다음 위치의 파일을 편집하세요 `/etc/panther-log-forwarder/`.
2. 검증: `sudo panther-log-forwarder validate`
3. 재시작: `sudo systemctl restart panther-log-forwarder`

### 자격 증명 회전

1. Panther Console에서 새 Bearer 토큰을 생성하세요.
2. 포워더 구성 파일의 토큰을 업데이트하세요.
3. 재시작: `sudo systemctl restart panther-log-forwarder`

### 업그레이드

1. 플랫폼에 맞는 새 릴리스 tarball과 체크섬을 다운로드하세요(참조 [다운로드 링크](#download-links)).
2. 체크섬을 확인하고, 압축을 풀고, 설치 프로그램을 실행하세요:

```bash
sha256sum -c panther-log-forwarder_linux_amd64.tar.gz.sha256
tar -xzf panther-log-forwarder_linux_amd64.tar.gz
cd panther-log-forwarder
sudo ./install.sh
```

설치 프로그램은 서비스가 실행 중이었다면 자동으로 다시 시작합니다. 업그레이드를 확인하세요:

```bash
sudo panther-log-forwarder --version
sudo panther-log-forwarder status
```

다음의 구성 파일은 `/etc/panther-log-forwarder/` 업그레이드 중 유지됩니다.

### 제거

```bash
sudo systemctl stop panther-log-forwarder
cd panther-log-forwarder   # 압축 해제된 설치 디렉터리
sudo ./uninstall.sh
```

***

## 파일 위치

| Path                                               | 목적        |
| -------------------------------------------------- | --------- |
| `/etc/panther-log-forwarder/panther.conf`          | 전역 설정     |
| `/etc/panther-log-forwarder/forwarders.d/*.yaml`   | 포워더 구성    |
| `/var/log/panther-log-forwarder/log-forwarder.log` | 로그 포워더 로그 |
| `/var/log/panther-log-forwarder/vector.log`        | Vector 로그 |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.panther.com/ko/data-onboarding/panther-log-forwarder.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.