G-BlackHole Documentation

Appearance

Yêu cầu ​

  • Đã cài blackhole-fwd trên host Windows hoặc Linux theo hướng dẫn Cài đặt (kiến trúc x86_64). Bản container cũng chạy theo cùng một file cấu hình — xem mục Container trong Cài đặt.
  • Trong các lệnh dưới, blackhole-fwd đã có trong PATH. Nếu chưa, hãy gọi bằng đường dẫn đầy đủ tới executable.
  • Một thư mục làm việc cố định: trên Windows là thư mục chứa executable (binary tự chuyển sang thư mục đó khi khởi động); trên Linux là thư mục bạn khởi chạy từ đó — service cũng dùng thư mục chứa executable.
  • Pipeline đầu tiên không cần Registry. Kết nối Registry là Bước 4, hoàn toàn tùy chọn.

Quy tắc giữa source, server và transform ​

Các ràng buộc sau được kiểm tra lúc khởi động và hot-reload — hãy nhớ trước khi viết cấu hình:

  • rsyslog source cần section rsyslog_server. Thiếu sẽ thấy cảnh báo No rsyslog server configured, rsyslog collector will not be created (không có collector nào được tạo).
  • snmp source cần section snmp_server, nếu không sẽ báo lỗi SNMP server config required.
  • mqtt source bắt buộc có broker, nếu không sẽ báo lỗi No broker URL found.
  • grpc_server chỉ khởi động khi có ít nhất một grpc source.
  • Trong transform, identifier và inputs là các key cùng cấp với các trường khác — KHÔNG đặt trong common:.
  • Đồ thị transform được validate lúc khởi động: input không tồn tại hoặc có vòng lặp sẽ bị từ chối (ví dụ Cycle detected in transforms graph!).

Bước 1: Tạo file cấu hình ​

File cấu hình mặc định là blackhole-fwd.yml trong thư mục làm việc (đây cũng là đường dẫn mặc định của --config). Dưới đây là pipeline tối giản: nhận syslog qua UDP/TCP 514, rồi ghi sự kiện ra thư mục ./debug-events/.

Linux:

bash
cat > blackhole-fwd.yml <<'EOF'
logging:
  level: "info"

rsyslog_server:
  udp_addr: "0.0.0.0:514"
  tcp_addr: "0.0.0.0:514"
  default_source: "rsyslog"

sources:
  rsyslog:
    type: rsyslog
    includes: []
    index: "syslog"
    sourcetype: "syslog_rfc3164"

sinks:
  out:
    type: file
    path: "./debug-events/"
EOF

Windows (PowerShell):

powershell
@'
logging:
  level: "info"

rsyslog_server:
  udp_addr: "0.0.0.0:514"
  tcp_addr: "0.0.0.0:514"
  default_source: "rsyslog"

sources:
  rsyslog:
    type: rsyslog
    includes: []
    index: "syslog"
    sourcetype: "syslog_rfc3164"

sinks:
  out:
    type: file
    path: "./debug-events/"
'@ | Set-Content -Path blackhole-fwd.yml -Encoding UTF8

Cấu trúc cần nhớ: sources, sinks, transforms đều là map ở top-level, khóa là id do bạn tự đặt và mỗi mục bắt buộc có type. Sink tham chiếu nguồn qua inputs (mặc định ["*"] = nhận mọi nguồn), nên ví dụ trên không cần khai inputs. Chi tiết xem Cấu hình.

Xác minh:

powershell
Test-Path .\blackhole-fwd.yml
bash
test -f blackhole-fwd.yml && echo OK

Kỳ vọng: True (Windows) hoặc OK (Linux) — file đã tồn tại đúng tên.

Bước 2: Sinh JSON Schema để kiểm tra cấu hình ​

bash
blackhole-fwd configure schema

Lệnh đọc file tại đường dẫn --config (mặc định blackhole-fwd.yml) và ghi config.jsonschema cùng thư mục với file cấu hình. Nếu YAML sai cú pháp hoặc dùng sai trường, lệnh sẽ báo lỗi parse và không tạo schema.

Xác minh:

powershell
Test-Path .\config.jsonschema
bash
ls -l config.jsonschema

Kỳ vọng: True / file config.jsonschema tồn tại — cấu hình đọc được.

Bước 3: Chạy thử ở foreground ​

bash
blackhole-fwd start --verbose
  • start là lệnh khởi động pipeline; chạy không kèm lệnh nào thì chỉ hiện banner, không chạy gì cả.
  • --verbose và --config là cờ toàn cục, đặt trước hay sau start đều được, ví dụ: blackhole-fwd --config /path/to/blackhole-fwd.yml start --verbose.
  • Dừng bằng Ctrl+C.

Gửi một message syslog test:

Linux (cần nc):

bash
echo '<134>Oct  6 12:00:00 testhost test: quickstart ping' | nc -u -w1 127.0.0.1 514

Windows (PowerShell):

powershell
$udp = New-Object System.Net.Sockets.UdpClient
$udp.Connect('127.0.0.1', 514)
$msg = [System.Text.Encoding]::ASCII.GetBytes('<134>Oct  6 12:00:00 testhost test: quickstart ping')
$udp.Send($msg, $msg.Length) | Out-Null
$udp.Close()

Xác minh:

powershell
Get-ChildItem .\debug-events
Get-Content .\logs\default.log -Tail 20
bash
ls -l debug-events/
tail -n 20 logs/default.log

Kỳ vọng: thư mục debug-events/ có file được tạo ra và chứa dữ liệu message vừa gửi; logs/default.log (nằm cạnh executable trên Windows, tại thư mục làm việc trên Linux) có dòng log mức debug vì đã bật --verbose, không có lỗi cấu hình.

ℹ️
Người dùng container: chạy cùng một file cấu hình này — mount vào /etc/blackhole/blackhole-fwd.yml như ví dụ trong [Cài đặt](./install), rồi kiểm tra bằng docker logs và đọc thư mục debug-events / logs trong volume mounted tại /home/nonroot.

Bước 4: Kết nối Registry (tùy chọn) ​

Chỉ thực hiện khi dùng Registry để quản lý tập trung.

4.1 — Thêm section registry: vào file cấu hình:

yaml
registry:
  api_url: "https://registry.example.com"
  api_key: "<api-key>"
  http_server:
    enabled: false
⚠️
registry.http_server.enabled mặc định là true. Khi file cấu hình có section registry:, Forwarder bắt buộc phải có registry.api_key (và device id) lúc khởi động, nếu không sẽ dừng với lỗi registry.rest_forwarder.enabled=true requires registry.api_key. Đây là lỗi gặp rất nhiều ở lần chạy đầu — hãy luôn đặt api_key, hoặc đặt http_server.enabled: false như ví dụ trên.
📝
Nếu có section registry: nhưng thiết bị chưa xác thực, Forwarder vẫn khởi động nhưng KHÔNG chạy collector nào và chỉ ghi cảnh báo Device is not active, no collectors will be started. Hãy chạy auth ở bước 4.2 trước khi mong đợi dữ liệu đi qua.

4.2 — Xác thực với Registry:

bash
blackhole-fwd auth --key "<api-key>"

Thiếu section registry: sẽ báo No registry configured. Khi thành công, lệnh đăng ký thiết bị rồi đẩy cấu hình local lên Registry. Nếu Registry không liên lạc được lúc khởi động, Forwarder chỉ ghi warning và tiếp tục chạy với cấu hình local.

Xác minh:

bash
blackhole-fwd start --verbose

Kỳ vọng: khởi động lại mà không còn cảnh báo Device is not active, no collectors will be started — collectors đã chạy. (Nếu auth thất bại, bạn sẽ thấy lại cảnh báo này.)

4.3 — Đồng bộ cấu hình (không bắt buộc):

bash
blackhole-fwd configure pull
blackhole-fwd configure push
  • configure pull tải cấu hình từ Registry về (cần có registry: và đã auth); muốn ghi ra file riêng thì thêm --output <PATH>.
  • configure push đẩy cấu hình local lên Registry. Chạy trước khi auth sẽ báo device token not available, you need to authenticate first.

Xác minh:

bash
blackhole-fwd configure push

Kỳ vọng: lệnh kết thúc mà không báo lỗi (đã xác thực). Nếu chưa auth, bạn sẽ thấy device token not available, you need to authenticate first.

Bước 5: Cài đặt như service ​

Sau khi pipeline chạy tốt ở foreground, cài service để chạy nền và tự khởi động cùng máy.

Windows (PowerShell chạy bằng Administrator):

powershell
blackhole-fwd service install

Linux:

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

Xác minh:

powershell
Get-Service -Name blackhole-fwd
bash
sudo systemctl status blackhole-fwd --no-pager

Kỳ vọng: Windows — trạng thái Running; Linux — active (running).

Xác minh ​

Chạy trọn bộ trên máy đã cài service:

Windows:

powershell
Get-Service -Name blackhole-fwd
Test-Path .\config.jsonschema
netstat -ano | findstr 514
Get-Content .\logs\default.log -Tail 20
Get-Content .\logs\default-error.log -Tail 10

Linux:

bash
sudo blackhole-fwd service status
test -f config.jsonschema && echo OK
ss -ulnp | grep 514
tail -n 20 logs/default.log
tail -n 10 logs/default-error.log

Kỳ vọng:

  • Service trạng thái đang chạy (Running / active (running) / service status báo chạy).
  • config.jsonschema tồn tại — cấu hình đọc được.
  • Port 514 (UDP) đang lắng nghe.
  • logs/default.log có dòng khởi động và các sự kiện gần đây; logs/default-error.log trống hoặc không có lỗi lặp lại.
  • Sau khi gửi message test syslog ở Bước 3, thư mục debug-events/ có file chứa message đó.
📝
Ở chế độ service, log ra console bị tắt nên journalctl -u blackhole-fwd gần như không có gì. Nguồn log duy nhất là file logs/default.log và logs/default-error.log nằm cùng thư mục với executable. Forwarder không ghi vào Windows Event Log.

Bước tiếp theo ​

  • Cấu hình — tham chiếu sources, sinks, transforms, registry
  • Cài đặt — MSI, installer script, container, gỡ cài đặt
  • Vận hành — service, hot-reload, giám sát vận hành

Released under the MIT License.

Copyright © 2024 G-BlackHole