G-BlackHole Documentation

Yêu cầu hệ thống

Thành phần	Yêu cầu
Kiến trúc	x86_64 (AMD64) — không có bản ARM64 hay 32-bit
Quyền	Administrator (Windows) hoặc root (Linux) để cài đặt service
Mạng	Truy cập HTTPS tới Registry nếu dùng quản lý tập trung
TLS	OpenSSL được build kèm binary (vendored) — không cần cài riêng

Theo nền tảng

Windows

Windows 10/11 hoặc Windows Server 2016 trở lên, 64-bit.
PowerShell 5.1 trở lên.
Quyền Administrator khi cài đặt service.

Linux

Phân phối Linux 64-bit. Bản x86_64-unknown-linux-gnu dùng cho máy có glibc; nếu không, dùng bản x86_64-unknown-linux-musl.
systemd hoặc OpenRC — bắt buộc nếu cài đặt bằng service install.
Thư viện chạy: glibc, libz, libsasl2, libzstd, zlib và CA certificates.

Khuyến nghị tài nguyên (sizing guidance)

Mã nguồn không ép mức RAM, disk hay CPU tối thiểu nào. Dựa trên các giá trị mặc định, bạn ước lượng tài nguyên theo bảng sau:

Hạng mục	Giá trị mặc định
Buffer của mỗi channel	100.000 sự kiện
Gói gửi (batch)	500 tin / 1000 ms / 10 MB
Persistent queue	tối đa 100.000 tin hoặc 256 MB
Cache của database (sled)	512 MB

Forwarder chỉ mở port khi có phần cấu hình tương ứng:

Listener	Port	Mở khi
rsyslog	UDP/TCP `514`	có `rsyslog` source kèm `rsyslog_server`
SNMP trap	UDP `162`	có `snmp` source kèm `snmp_server`
MQTT broker	TCP `1883`	có section `mqtt_server`
gRPC	TCP `50051`	có `grpc_server` và ít nhất một `grpc` source
HTTP proxy	TCP `8080`	có section `proxy_server`
HTTP của Forwarder	TCP `18080`	có section `registry:` với `http_server.enabled`

Cài đặt trên Windows

Tải bộ cài từ trang GitHub Releases. Mỗi bản release của blackhole-fwd gồm file .msi, installer .ps1, archive .zip và checksum .sha256 (bản x64 Windows: blackhole-fwd-x86_64-pc-windows-msvc.*).

Phương án 1: MSI (khuyến nghị)

MSI cài theo máy (per-machine) vào C:\Program Files\blackhole-fwd\, đặt executable trong thư mục bin\ của nó và thêm thư mục đó vào system PATH:

powershell

msiexec /i blackhole-fwd-x86_64-pc-windows-msvc.msi

📝

MSI chỉ cài binary và thêm PATH. MSI không đăng ký service, không tạo file cấu hình, không mở firewall, không tạo thư mục log và không xác thực với Registry — đó là các bước riêng, xem [Quickstart](./quickstart).

Phương án 2: Installer script từ GitHub Releases

powershell

powershell -ExecutionPolicy Bypass -c "irm https://github.com/gcsclabs/siem-agent/releases/download/v0.7.5/blackhole-fwd-installer.ps1 | iex"

Script cài vào thư mục bin mặc định của Cargo: %USERPROFILE%\.cargo\bin.

Phương án 3: Tải archive .zip

powershell

Expand-Archive .\blackhole-fwd-x86_64-pc-windows-msvc.zip -DestinationPath .\blackhole-fwd

Archive chứa blackhole-fwd.exe ở thư mục gốc. Bạn có thể copy blackhole-fwd.exe vào bất kỳ thư mục nào (ví dụ .\blackhole-fwd\).

⚠️

Thư mục làm việc quyết định đường dẫn cấu hình mặc định (blackhole-fwd.yml), thư mục logs và vị trí database. Trên Windows, binary tự chuyển sang thư mục chứa chính nó khi khởi động — hãy đặt executable vào một thư mục cố định, và nếu cấu hình nằm ở chỗ khác hãy truyền --config bằng đường dẫn tuyệt đối.

Xác minh (Windows)

powershell

Get-Command blackhole-fwd | Select-Object -ExpandProperty Source
blackhole-fwd --version

Kỳ vọng:

Với MSI: đường dẫn trả về là C:\Program Files\blackhole-fwd\bin\blackhole-fwd.exe.
Lệnh thứ hai in ra số phiên bản của binary (ví dụ 0.7.5) và thoát.

Nếu blackhole-fwd không có trong PATH, hãy gọi bằng đường dẫn đầy đủ, ví dụ & "$env:USERPROFILE\.cargo\bin\blackhole-fwd.exe" --version.

Cài đặt trên Linux

Tải bộ cài từ trang GitHub Releases. Bản x64 Linux có hai biến thể: blackhole-fwd-x86_64-unknown-linux-gnu.tar.xz và blackhole-fwd-x86_64-unknown-linux-musl.tar.xz.

Phương án 1: Installer script từ GitHub Releases (khuyến nghị)

bash

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/gcsclabs/siem-agent/releases/download/v0.7.5/blackhole-fwd-installer.sh | sh

Script cài vào thư mục bin mặc định của Cargo: ~/.cargo/bin.

Phương án 2: Tải archive .tar.xz

bash

tar -xJf blackhole-fwd-x86_64-unknown-linux-gnu.tar.xz
./blackhole-fwd-x86_64-unknown-linux-gnu/blackhole-fwd --version

Archive giải nén ra thư mục blackhole-fwd-x86_64-unknown-linux-gnu/ chứa binary blackhole-fwd. Bạn có thể copy binary vào bất kỳ thư mục nào và tự đặt quyền thực thi:

bash

chmod +x blackhole-fwd-x86_64-unknown-linux-gnu/blackhole-fwd
mkdir -p ~/blackhole-fwd
cp blackhole-fwd-x86_64-unknown-linux-gnu/blackhole-fwd ~/blackhole-fwd/

⚠️

Thư mục làm việc quyết định đường dẫn cấu hình mặc định (blackhole-fwd.yml), thư mục logs và vị trí database — trên Linux binary không tự đổi thư mục. Hãy đặt binary vào một thư mục cố định, và nếu cấu hình nằm ở chỗ khác hãy truyền --config bằng đường dẫn tuyệt đối.

Xác minh (Linux)

bash

~/.cargo/bin/blackhole-fwd --version

Kỳ vọng: in ra số phiên bản của binary (ví dụ 0.7.5) và thoát. Nếu bạn đã copy binary sang thư mục khác, gọi theo đường dẫn đó, ví dụ ~/blackhole-fwd/blackhole-fwd --version.

Cài đặt service (tùy chọn)

bash

sudo blackhole-fwd service install

Lệnh này ghi file service /etc/systemd/system/blackhole-fwd.service (cần root và systemd; hệ thống dùng OpenRC cũng được hỗ trợ), tự khởi động service ngay và bật chạy khi khởi động máy. Đặt file cấu hình blackhole-fwd.yml cạnh executable trước khi chạy lệnh này.

⚠️

service install chỉ ghi nhận đúng lệnh blackhole-fwd --service --service-name blackhole-fwd — tham số --config truyền kèm sẽ KHÔNG được lưu lại. Service tự đọc cấu hình từ thư mục làm việc, tức là thư mục chứa executable, nên file blackhole-fwd.yml phải nằm cạnh binary. service install đã khởi động service ngay, nên service start phía sau là thừa. Nếu service đã tồn tại, lệnh sẽ báo Service already exists. Use --force to overwrite.

Xác minh:

bash

sudo blackhole-fwd service status

Kỳ vọng: trạng thái service đang chạy. Xem thêm Quickstart về vị trí file log của service.

Triển khai bằng Container

Image: ghcr.io/gcsclabs/blackhole-forwarder — nền tảng distroless (gcr.io/distroless/cc-debian12:nonroot), chạy bằng user nonroot (uid 65532), chỉ có bản linux/amd64. Image được phát hành cùng dòng release hiện tại trên GitHub Container Registry.

Các tính chất cần biết:

Không có shell, không có package manager, không có công cụ debug (xem Warning bên dưới).
ENTRYPOINT là blackhole-fwd, CMD mặc định là --config /etc/blackhole/blackhole-fwd.yml start — chỉ cần mount file cấu hình đúng chỗ là chạy được ngay.
Working directory là /home/nonroot (uid 65532 được ghi): database blackhole-fwd.db và thư mục logs/ được tạo tại đây.
Cấu hình chỉ được đọc lúc khởi động và khi hot-reload nên mount read-only là đủ.
Image không có lệnh EXPOSE và không publish port nào mặc định.

Chạy thử với Docker:

bash

docker run -d --name blackhole-fwd \
  -v /host/blackhole-fwd.yml:/etc/blackhole/blackhole-fwd.yml:ro \
  -v blackhole-data:/home/nonroot \
  -p 514:514/udp \
  ghcr.io/gcsclabs/blackhole-forwarder:latest

⚠️

Image là distroless nên KHÔNG có shell: docker exec -it blackhole-fwd bash sẽ thất bại. Hãy dùng docker logs (hoặc kubectl logs trên Kubernetes), hoặc mount data volume và kiểm tra file từ host.

📝

Port không được publish mặc định. Source rsyslog nghe UDP/TCP 514 nên phải khai báo rõ -p 514:514/udp (hoặc -p 514:514/tcp). Các listener khác — SNMP trap 162, MQTT 1883, gRPC 50051, proxy 8080, HTTP 18080 — chỉ mở khi có section cấu hình tương ứng, và bạn phải thêm -p cho từng port đó.

📝

Hãy mount một volume tại /home/nonroot (như ví dụ trên) để giữ blackhole-fwd.db và logs/ qua các lần restart. Trên Kubernetes, cùng logic áp dụng với một PersistentVolumeClaim mount vào /home/nonroot, và xem log bằng kubectl logs.

Xác minh (Container):

bash

docker ps --filter name=blackhole-fwd
docker logs blackhole-fwd

Kỳ vọng: container ở trạng thái Up, và docker logs cho thấy Forwarder khởi động mà không báo lỗi cấu hình.

Gỡ cài đặt

Windows:

powershell

blackhole-fwd service stop
blackhole-fwd service uninstall
msiexec /x blackhole-fwd-x86_64-pc-windows-msvc.msi

Linux:

bash

sudo blackhole-fwd service stop
sudo blackhole-fwd service uninstall
rm ~/.cargo/bin/blackhole-fwd

Container:

bash

docker stop blackhole-fwd
docker rm blackhole-fwd
docker volume rm blackhole-data

Khắc phục sự cố cài đặt

Vấn đề	Nguyên nhân	Giải pháp
`Failed to read file for hashing: blackhole-fwd.yml`	File cấu hình không tồn tại tại đường dẫn truyền cho `--config`	Tạo `blackhole-fwd.yml` tại đúng thư mục làm việc (xem Quickstart)
`Service already exists. Use --force to overwrite.`	Service `blackhole-fwd` đã được cài trước đó	Chạy `blackhole-fwd service uninstall` rồi cài lại, hoặc `blackhole-fwd service install --force`
`Access Denied` khi `service install` trên Windows	Chưa chạy với quyền Administrator	Mở PowerShell bằng Run as Administrator
`service install` thất bại trên Linux	Thiếu quyền root, hoặc máy không có systemd/OpenRC	Chạy bằng `sudo`; cài systemd hoặc OpenRC
`registry.rest_forwarder.enabled=true requires registry.api_key`	Có section `registry:` nhưng thiếu `registry.api_key`	Thêm `registry.api_key`, hoặc đặt `registry.http_server.enabled: false` (lưu ý: nếu chưa từng `auth`, bạn có thể gặp `device_id is not available` trước)
`No registry configured` khi chạy `auth`	Chưa khai báo section `registry:` trong cấu hình	Thêm `registry:` với `api_url` vào file cấu hình rồi chạy lại
`device token not available, you need to authenticate first`	Chạy `configure push` trước khi xác thực	Chạy `blackhole-fwd auth --key ...` trước
`Device is not active, no collectors will be started`	Có `registry:` nhưng thiết bị chưa được xác thực/activated	Chạy `blackhole-fwd auth --key ...`; xem Quickstart
`No rsyslog server configured, rsyslog collector will not be created` / `SNMP server config required` / `No broker URL found`	Source thiếu server hoặc broker tương ứng	Thêm `rsyslog_server:` / `snmp_server:` / `broker` cho source đó
`docker exec ... bash` báo lỗi	Image distroless không có shell	Dùng `docker logs` / `kubectl logs`
`journalctl -u blackhole-fwd` hầu như không có gì	Ở chế độ service, stdout bị tắt — Forwarder ghi log vào file	Xem `logs/default.log` và `logs/default-error.log` (cùng thư mục với executable)
Cấu hình báo `unknown variant` khi đọc	Dùng `type` không có trong binary này	Kiểm tra lại danh sách source/sink/transform được hỗ trợ ở Cấu hình
Binary không chạy trên máy	Sai kiến trúc (ARM64/32-bit) hoặc sai biến thể libc	Dùng bản x86_64 phù hợp: `...-linux-gnu` hoặc `...-linux-musl`

Bước tiếp theo

Quickstart — dựng pipeline đầu tiên end-to-end
Cấu hình — tham chiếu đầy đủ sources, sinks, transforms
Vận hành — quản lý service, hot-reload, giám sát
Troubleshooting — chẩn đoán khi đã chạy

Yêu cầu hệ thống ​

Theo nền tảng ​

Windows ​

Linux ​

Khuyến nghị tài nguyên (sizing guidance) ​

Cài đặt trên Windows ​

Phương án 1: MSI (khuyến nghị) ​

Phương án 2: Installer script từ GitHub Releases ​

Phương án 3: Tải archive .zip ​

Xác minh (Windows) ​

Cài đặt trên Linux ​

Phương án 1: Installer script từ GitHub Releases (khuyến nghị) ​

Phương án 2: Tải archive .tar.xz ​

Xác minh (Linux) ​

Cài đặt service (tùy chọn) ​

Triển khai bằng Container ​

Gỡ cài đặt ​

Khắc phục sự cố cài đặt ​

Bước tiếp theo ​

Yêu cầu hệ thống

Theo nền tảng

Windows

Linux

Khuyến nghị tài nguyên (sizing guidance)

Cài đặt trên Windows

Phương án 1: MSI (khuyến nghị)

Phương án 2: Installer script từ GitHub Releases

Phương án 3: Tải archive .zip

Xác minh (Windows)

Cài đặt trên Linux

Phương án 1: Installer script từ GitHub Releases (khuyến nghị)

Phương án 2: Tải archive .tar.xz

Xác minh (Linux)

Cài đặt service (tùy chọn)

Triển khai bằng Container

Gỡ cài đặt

Khắc phục sự cố cài đặt

Bước tiếp theo