Giới thiệu

BlackHole Forwarder (binary blackhole-fwd) là thành phần trung gian trong hệ thống SIEM. Nó nhận dữ liệu từ nhiều Agent và thiết bị mạng (syslog, SNMP, MQTT, Kafka, gRPC), xử lý qua pipeline transform rồi chuyển tiếp (ship) tới backend: gRPC, Kafka, MQTT, OpenSearch/BlackHole, file hoặc alert.

Khác với Agent, Forwarder là phía mở port lắng nghe: mỗi embedded server (rsyslog, SNMP, MQTT, gRPC, proxy, HTTP next-hop) chỉ mở port khi có section cấu hình tương ứng, xem Port lắng nghe.

Forwarder chạy hoàn toàn với cấu hình local, hoặc nhận cấu hình từ Registry khi đã xác thực (auth --key).

Tính năng chính

Thu thập dữ liệu

Source	Mô tả
rsyslog	Nhận syslog từ thiết bị mạng qua UDP/TCP 514 (cần section rsyslog_server)
snmp	Nhận SNMP trap qua UDP 162 (cần section snmp_server); poll thiết bị ra UDP 161
mqtt	Đọc dữ liệu từ MQTT broker
kafka	Đọc từ Kafka topic
grpc	Nhận dữ liệu qua gRPC (cần section grpc_server)

Xử lý dữ liệu

• Transforms: filter, remap (VRL), route, dedupe, reduce, throttle, ingestion_rule
• Routing: nối nhiều source và nhiều sink qua inputs, có fan-in/fan-out
• Persistent queue: message chưa gửi được nằm trong database local blackhole-fwd.db, sẽ gửi lại ở lần khởi động sau
• Hot-reload: đọc lại cấu hình local khi đang chạy (phạm vi có giới hạn, xem ./operation)
• Resource guard: CPU/memory quá tải kéo dài thì tạm dừng pipeline thay vì tắt process, xem ./operation

Tích hợp

Sink	Mô tả
grpc	Gửi tới endpoint gRPC (thường là BlackHole server)
kafka	Gửi tới Kafka topic
mqtt	Publish tới MQTT broker
blackhole	OpenSearch/BlackHole indexing (type của sink OpenSearch)
file	Ghi ra file local (gỡ lỗi, lưu trữ cục bộ)
alert	Phát cảnh báo về Registry qua POST {api_url}/client/alerts

• Embedded servers: rsyslog, SNMP trap, MQTT broker, gRPC, HTTP CONNECT proxy, HTTP next-hop (REST forwarder)
• Registry: đăng ký thiết bị, pull/push cấu hình từ server trung tâm (auth --key, configure pull, configure push)
• Service: chạy như Windows Service hoặc systemd/OpenRC service
• Container: image distroless không có shell, xem Cài đặt

Nền tảng hỗ trợ

Nền tảng	Chi tiết
Windows	Windows 10/11, Windows Server 2016 trở về sau. Kiến trúc x86_64.
Linux	Ubuntu, Debian, CentOS, RHEL, Alpine. Kiến trúc x86_64. Alpine dùng musl libc.

⚠️

Chỉ có build x86_64. Không có bản ARM64, không có bản cho Apple Silicon.

Yêu cầu hệ thống

ℹ️

Không có mức tài nguyên tối thiểu nào được ép buộc trong mã nguồn. Bảng dưới đây là **gợi ý quy mô**, suy ra từ các giá trị mặc định của pipeline, không phải yêu cầu bắt buộc.

Hạng mục	Giá trị mặc định
Channel buffer	100.000 event mỗi bên (channel_buffers)
Batch gửi đi	500 message / 1000 ms / 10 MB
Persistent queue	100.000 message hoặc 256 MB (inventory)
Database cache	512 MB cho database local blackhole-fwd.db
Log	max_size_mb 10 MB

Forwarder chỉ mở port khi có section cấu hình tương ứng (514, 162, 1883, 50051, 8080, 18080), xem Port lắng nghe. Càng nhiều source chạy song song và càng nhiều event/giây thì càng cần CPU và RAM lớn hơn; khi vượt ngưỡng resource guard, pipeline bị tạm dừng thay vì process bị tắt.

Yêu cầu theo nền tảng và cách cài, xem Cài đặt.

Bảo mật

• Xác thực với Registry bằng API key (auth --key), sau đó trao đổi bằng device token
• Device guard: danh sách chặn (deny-list) token thiết bị, giữ trong bộ nhớ và cập nhật theo trạng thái thiết bị từ Registry. Không có khóa cấu hình YAML nào cho nó, và danh sách rỗng nghĩa là cho phép tất cả, xem ./operation
• TLS có sẵn cho MQTT server, gRPC server, HTTP next-hop và các sink MQTT/Kafka/gRPC/OpenSearch, nhưng tắt mặc định, đừng giả định kết nối đã được mã hóa
• Authentication cho MQTT broker và Basic Auth cho HTTP CONNECT proxy

⚠️

Forwarder chạy bằng quyền **root** (Linux) hoặc **LocalSystem** (Windows) khi chạy như service, chưa có cơ chế hạ quyền (privilege dropping). Hãy giới hạn quyền truy cập thư mục cài đặt và file cấu hình.

Logging

Trường	Mặc định	Mô tả
level	info	trace, debug, info, warn, error, hỗ trợ cả per-target như rsyslog=debug
dir	./logs	Thư mục log, resolve tương đối so với thư mục làm việc
file	default.log	Log chính
error_file	default-error.log	Log lỗi
max_size_mb	10	Tổng dung lượng log, quyết định kích thước mỗi file rotation

File log thực tế là logs/default.log và logs/default-error.log (relative tới thư mục làm việc của process). Rotation luôn bật, không có công tắc tắt. Ở chế độ service, stdout bị tắt nên file log là nơi duy nhất có output.

Chi tiết cách tìm thư mục log và đọc log, xem ./operation.

Xem thêm

• ./quickstart - Chạy Forwarder lần đầu
• ./install - Cài đặt và cài service
• ./configuration - Tham chiếu cấu hình
• ./operation - Vận hành hằng ngày
• ./troubleshooting - Khắc phục sự cố
• /components/agent/overview - Agent là gì