G-BlackHole Documentation

Appearance

Thu thập thông tin ​

Khi báo lỗi hoặc cần hỗ trợ, chuẩn bị sẵn:

  • Phiên bản: blackhole-fwd --version
  • File log: logs/default.log và logs/default-error.log; trên Linux service còn journalctl -u blackhole-fwd --since "<thời điểm>" (chỉ chứa stderr)
  • Cấu hình đang dùng và file .blackhole-resolved.yaml đi kèm (che API key, token, credential trước khi gửi)
  • Cách chạy: foreground, service hay container; hệ điều hành và phiên bản
  • Các bước tái hiện lỗi và mốc thời gian
📝
Lỗi khởi động (sai YAML, `Failed to read file for hashing`, thiếu `registry.api_key`, `No broker URL found`) thường được in ra **stderr** chứ không vào file log. Khi chạy service mà không thấy gì trong `logs/`, hãy tái hiện bằng lệnh foreground từ cùng thư mục cấu hình để đọc thông báo lỗi trực tiếp.

Bảng triệu chứng ​

Triệu chứngMục
Khởi động thoát ngay: Failed to read file for hashingThiếu file cấu hình
Khởi động thoát ngay: registry.rest_forwarder.enabled=true requires registry.api_keyThiếu api_key / device id
Khởi động thoát ngay, lỗi YAML/parseCấu hình sai cú pháp
Khởi động thoát ngay: Startup blocked due to resource constraintsBị chặn khi khởi động
Service already exists. Use --force to overwrite.Service đã tồn tại
Sửa cấu hình không có tác dụngService dùng sai cấu hình
Cảnh báo Failed to pull remote config / Failed to fetch remote configurationRegistry không tới được
device token not available, you need to authenticate firstChưa xác thực
Service chạy nhưng không có dữ liệu ra sinkKhông có dữ liệu
Source rsyslog/snmp/grpc không nhận dữ liệuThiếu section server
No broker URL foundMQTT source thiếu broker
gRPC trả permission_deniedDevice bị chặn
Có section cấu hình nhưng port không mởPort bị chiếm
Pipeline dừng giữa chừng, process vẫn sốngBị tạm dừng
Không docker exec vào được containerContainer không có shell

Lỗi khởi động ​

Thiếu file cấu hình ​

Triệu chứng: Lệnh blackhole-fwd start thoát ngay trước khi chạy pipeline, stderr báo:

Failed to read file for hashing: blackhole-fwd.yml

Khi chạy service, process cũng dừng ngay; file log chỉ có vài dòng đầu.

Nguyên nhân: File tại đường dẫn --config (mặc định blackhole-fwd.yml trong thư mục làm việc) không tồn tại. Ngay cả khi process thử config.yml / config.yaml lúc nạp cấu hình, bước khởi tạo watcher vẫn băm (hash) đúng đường dẫn --config nên vẫn thất bại.

Giải pháp:

  1. Xác định thư mục làm việc của process: readlink /proc/$(pgrep -x blackhole-fwd)/cwd (Linux). Trên Windows là thư mục chứa executable.
  2. Tạo file blackhole-fwd.yml tại đúng thư mục đó, hoặc truyền --config trỏ tới file có thật: blackhole-fwd -c /path/to/blackhole-fwd.yml start.
  3. Với service: đặt blackhole-fwd.yml (hoặc config.yml / config.yaml) vào thư mục chứa executable rồi chạy lại service start, service không lưu --config.

Xác minh:

bash
ls -l blackhole-fwd.yml
grep "Entering main processing loop" logs/default.log | tail -1

Kỳ vọng: file tồn tại tại đúng đường dẫn --config, không còn thông báo Failed to read file for hashing, và sau khi chạy lại blackhole-fwd start (hoặc service start) log có dòng Entering main processing loop. Press Ctrl+C to stop..

Thiếu api_key hoặc device id ​

Triệu chứng: Forwarder thoát ngay khi khởi động với một trong hai thông báo:

registry.rest_forwarder.enabled=true requires registry.api_key
device_id is not available

Nguyên nhân: Cấu hình có section registry: khiến registry.http_server.enabled (mặc định true) bật HTTP next-hop ở cổng 18080. Lúc đó startup yêu cầu cả registry.api_key lẫn device id, device id chỉ có sau khi đã xác thực (auth --key) và được lưu trong database local.

Giải pháp:

  1. Xác thực trước khi khởi động: blackhole-fwd auth --key "<API key>" (cần registry.api_url trong cấu hình).
  2. Thêm registry.api_key vào section registry: của file cấu hình:
yaml
registry:
  api_url: "https://<registry-host>"
  api_key: "<API key>"
  1. Không cần next-hop thì tắt nó: registry.http_server.enabled: false (khi đó cổng 18080 và endpoint /health cũng không có).
  2. Chạy độc lập, không quản lý tập trung thì xoá hẳn section registry: rồi khởi động lại.

Xác minh:

bash
# Tái hiện lúc còn lỗi, xem phần stderr:
blackhole-fwd start 2>&1 | grep -E "requires registry.api_key|device_id is not available"
# kỳ vọng: in ra đúng thông báo lỗi đó

# Sau khi khắc phục:
grep "Orchestrator started successfully" logs/default.log | tail -1
# có dòng mới

curl -s http://127.0.0.1:18080/health   # nếu vẫn bật listener
# {"status":"ok"}

Cấu hình sai cú pháp ​

Triệu chứng: Process thoát ngay, console in thông báo lỗi YAML hoặc lỗi thiếu trường (ví dụ mapping values are not allowed here, missing field ...). Chạy service thì gần như không thấy gì, file log không có thông báo lỗi.

Nguyên nhân: File cấu hình sai cú pháp YAML hoặc thiếu trường bắt buộc. Việc kiểm tra cấu hình chỉ xảy ra lúc khởi động (và lúc nhận config từ Registry), không có lệnh config validate. Lỗi đọc cấu hình lại diễn ra trước khi hệ thống log khởi tạo nên không ghi vào file log.

Giải pháp:

  1. Chạy foreground từ đúng thư mục cấu hình để đọc lỗi trực tiếp:
bash
blackhole-fwd start; echo $?
  1. Sửa lỗi theo đúng thông báo (dấu chấm-indent, trường thiếu, kiểu dữ liệu).
  2. Đối chiếu schema chính thức: blackhole-fwd configure schema rồi kiểm tra file config.jsonschema nằm cạnh file cấu hình.
  3. Khởi động lại service sau khi đã sửa xong.

Xác minh:

bash
blackhole-fwd start; echo $?

Kỳ vọng khi còn lỗi: thông báo lỗi + mã thoát 1. Khi đã đúng: process chạy tiếp, và grep "Orchestrator started successfully" logs/default.log | tail -1 có dòng mới.

Bị chặn khi khởi động do tài nguyên ​

Triệu chứng: Khởi động thất bại ngay, log có (mức ERROR) và stderr có:

Startup blocked due to resource constraints: CPU usage (92.00%) is at or above threshold (80.00%)

Nguyên nhân: Resource guard kiểm tra CPU/memory/disk ngay lúc khởi động. Metric nào đang bật (ngưỡng ≤ 100) mà giá trị hiện tại ≥ ngưỡng thì process không cho chạy tiếp.

Giải pháp:

  1. Giải phóng tài nguyên máy (đóng process đang chiếm CPU/memory) rồi khởi động lại.
  2. Hoặc nâng ngưỡng trong resources_threshold (vd. cpu.threshold_percentage: 95.0).
  3. Hoặc đặt ngưỡng > 100 để tắt theo dõi metric đó, mặc định disk.threshold_percentage: 101.0 chính là tắt.
  4. Nhớ khởi động lại: ngưỡng chỉ được đọc một lần lúc khởi động.

Xác minh:

bash
grep "Startup resource check" logs/default.log | tail -2
# kỳ vọng dòng: "Startup resource check passed - all resources within acceptable limits"

grep "Startup blocked due to resource constraints" logs/default.log | tail -1
# chỉ còn các dòng trước khi khắc phục

Service ​

Service đã tồn tại ​

Triệu chứng: blackhole-fwd service install thất bại với thông báo:

Service already exists. Use --force to overwrite.

Nguyên nhân: Service đã được cài trước đó. Lệnh install không ghi đè service hiện có.

Giải pháp:

  1. Chỉ muốn khởi động service đang có: blackhole-fwd service start (hoặc systemctl start blackhole-fwd / Start-Service blackhole-fwd).
  2. Muốn cài lại (ghi đè, uninstall rồi cài mới): blackhole-fwd service install --force.
  3. Muốn gỡ hẳn: blackhole-fwd service uninstall.

Xác minh:

bash
blackhole-fwd service install --force
blackhole-fwd service status

Kỳ vọng: install thành công không báo lỗi, status in ✅ Service is running.

Service dùng sai cấu hình ​

Triệu chứng: Đã sửa file cấu hình nhưng không có tác dụng: log, port hoặc pipeline vẫn như cũ. File .blackhole-resolved.yaml bên cạnh file mình sửa không được ghi lại.

Nguyên nhân: service install ghi nhận service là <executable> --service --service-name blackhole-fwd, không có --config nên mọi tham số cấu hình lúc cài bị bỏ qua. Service tự tìm cấu hình từ thư mục làm việc (Linux: thư mục chứa executable; Windows: process tự chuyển về thư mục chứa executable). Ngoài ra, cấu hình có thể đang do Registry quản lý (nguồn remote) hoặc lấy từ database (persisted) nên sửa local bị bỏ qua.

Giải pháp:

  1. Xác định process đang chạy với tham số nào và thư mục nào:
bash
sudo tr '\0' ' ' < /proc/$(pgrep -x blackhole-fwd)/cmdline; echo
sudo readlink /proc/$(pgrep -x blackhole-fwd)/cwd
  1. Linux: đặt blackhole-fwd.yml (hoặc config.yml / config.yaml) vào thư mục chứa executable, rồi service stop + service start.
  2. Windows: sửa file nằm ngay cạnh blackhole-fwd.exe.
  3. Kiểm tra nguồn cấu hình hiệu lực qua log Resolved config snapshot written (source: ...). Nếu là remote, cấu hình do Registry quản lý, sửa local sẽ bị bỏ qua (Remote config is active — ignoring local config change).
  4. Đọc cấu hình hiệu lực thực tế trong file .blackhole-resolved.yaml nằm cạnh file cấu hình đang dùng.

Xác minh:

bash
grep "Resolved config snapshot written" logs/default.log | tail -1
# kỳ vọng source: local (hoặc remote nếu chủ đích dùng Registry)

grep "Local config reloaded successfully" logs/default.log | tail -1
# sau khi sửa config đúng chỗ: có dòng mới trong ~6 giây

Registry và xác thực ​

Registry không tới được ​

Triệu chứng: Log có cảnh báo lặp lại:

Failed to pull remote config: ...
Failed to fetch remote configuration: ...

Forwarder vẫn chạy với cấu hình local hoặc persisted, không thoát process.

Nguyên nhân: Không kết nối được registry.api_url, do mạng, DNS, firewall, Registry đang dừng hoặc lỗi TLS.

Giải pháp:

  1. Kiểm tra kết nối HTTP tới Registry: curl -sS -o /dev/null -w "%{http_code}\n" https://<registry-host>/ (kỳ vọng 200/301/404, không phải timeout).
  2. Kiểm tra DNS: nslookup <registry-host>.
  3. Kiểm tra firewall/egress của máy Forwarder với cổng 443 (hoặc cổng của api_url).
  4. Không cần khởi động lại: process tự retry ở chu kỳ kế tiếp và không bao giờ thoát vì lỗi này. Hết warning khi Registry hồi phục.

Xác minh:

bash
grep "Failed to fetch remote configuration" logs/default.log | tail -3
# các dòng ngừng tăng sau khi Registry hồi phục

blackhole-fwd service status   # hoặc: pgrep -x blackhole-fwd
# process vẫn đang chạy

Chưa xác thực đã push/pull ​

Triệu chứng:

  • blackhole-fwd configure push thất bại: device token not available, you need to authenticate first
  • blackhole-fwd auth --key ... thất bại: No registry configured

Nguyên nhân: Chưa có device token (chưa auth) hoặc cấu hình thiếu section registry: (tối thiểu registry.api_url).

Giải pháp:

  1. Thêm section registry: với api_url vào file cấu hình:
yaml
registry:
  api_url: "https://<registry-host>"
  1. Xác thực: blackhole-fwd auth --key "<API key>".
  2. Kiểm tra log có Authentication successful! và Configuration pushed to remote server successfully.
  3. Chạy lại blackhole-fwd configure push.

Xác minh:

bash
blackhole-fwd auth --key "<API key>"; echo $?
# kỳ vọng: 0, và log/console có "Authentication successful!"

blackhole-fwd configure push; echo $?
# kỳ vọng: 0

Nếu sau auth log vẫn cảnh báo Device is not active thì device chưa được duyệt ở trạng thái Active trên Registry, xem mục Không có dữ liệu.

Không nhận được dữ liệu ​

Service đã cài nhưng không có dữ liệu ​

Triệu chứng: Service ở trạng thái chạy (✅ Service is running), không có lỗi, nhưng không có sự kiện nào ra sink. Trong log lặp lại:

Device is not active, no collectors will be started

Nguyên nhân: Cấu hình có section registry: nhưng device chưa được xác thực hoặc chưa ở trạng thái Active trên Registry. Khi đó Forwarder khởi động bình thường nhưng không start collector nào, không có gì để thu thập.

Giải pháp:

  1. Xác thực với API key: blackhole-fwd auth --key "<API key>".
  2. Xem log auth có Device is not active không, nếu có, device chưa Active: mở Registry, đặt device về trạng thái Active.
  3. Khởi động lại service: service stop rồi service start.
  4. Không dùng Registry thì xoá section registry:, pipeline chạy hoàn toàn với cấu hình local.

Xác minh:

bash
grep "Device is not active, no collectors will be started" logs/default.log | tail -1
# chỉ còn dòng trước thời điểm auth và restart

grep "Orchestrator started successfully" logs/default.log | tail -1
# có dòng mới

# kiểm tra dữ liệu thật ra sink (file sink ví dụ):
ls -l ./debug-events/    # tùy sink đang cấu hình

Source không khởi động vì thiếu section server ​

Triệu chứng: Source khai báo trong sources nhưng không nhận data. Trong log có một trong các cảnh báo:

No rsyslog server configured, rsyslog collector will not be created
No SNMP server configured, SNMP collector will not be created
gRPC server configured but no gRPC sources defined; server will not be started

Với gRPC, dấu hiệu khác: không có gì listen trên cổng 50051 dù đã khai source grpc.

Nguyên nhân: rsyslog và snmp là source thụ động, chúng chỉ chạy khi có embedded server section tương ứng nhận kết nối. grpc_server thì chỉ khởi động khi có ít nhất một source grpc.

Giải pháp:

  1. Thêm section còn thiếu vào cấu hình: rsyslog_server: cho source rsyslog, snmp_server: cho source snmp, grpc_server: cho source grpc.
  2. Với gRPC: đảm bảo có cả grpc_server và ít nhất một source type: grpc.
  3. Khởi động lại service, mọi section *_server không hot-reload.
  4. Kiểm tra port đã mở theo bảng port.

Xác minh:

bash
grep -E "No rsyslog server configured|No SNMP server configured|no gRPC sources defined" logs/default.log | tail -3
# không còn dòng mới sau khi thêm section

sudo ss -tulnp | grep -E ':(514|162|50051)'
# các port tương ứng đã có dòng LISTEN của blackhole-fwd

MQTT source bị từ chối: No broker URL found ​

Triệu chứng: Khởi động thất bại, stderr (và journal khi chạy service) có:

No broker URL found

Nguyên nhân: Source có type: mqtt nhưng không khai block broker: nên không có URL để kết nối. Lỗi xảy ra lúc start collector nên pipeline không chạy tiếp.

Giải pháp:

  1. Bổ sung broker.url cho source MQTT:
yaml
sources:
  mqtt_in:
    type: mqtt
    broker:
      url: "mqtt://<broker-host>:1883"
    topics: ["agents/+/data"]
  1. Kiểm tra lại URL đúng chuẩn (mqtt:// hoặc mqtts://) và broker có truy cập được từ máy Forwarder.
  2. Khởi động lại (thay đổi source yêu cầu restart).

Xác minh:

bash
# Tái hiện lúc còn lỗi, xem phần stderr:
blackhole-fwd start 2>&1 | grep "No broker URL found"
# kỳ vọng: in ra thông báo lỗi này

# Sau khi sửa:
grep "Started MQTT client" logs/default.log | tail -1
# kỳ vọng: dòng mới sau khi khởi động lại

Device bị từ chối bởi device guard ​

Triệu chứng: Client gRPC kết nối tới Forwarder bị từ chối với permission_denied (device is disabled by supervisor guard), stream đang mở bị ngắt. Trong log có:

Terminating gRPC stream because device token <token> was disabled by supervisor guard

Nguyên nhân: Device guard là danh sách chặn token giữ trong bộ nhớ, cập nhật từ Registry theo trạng thái device. Device không ở trạng thái Active thì token bị đưa vào danh sách. Lưu ý: danh sách rỗng thì cho phép mọi token, đây là deny-list, không phải allow-list, và không có khóa YAML nào cấu hình nó.

Giải pháp:

  1. Ở Registry: đặt lại device đó về trạng thái Active, token được gỡ khỏi deny-list ngay khi trạng thái thay đổi.
  2. Với client đã bị ngắt stream: kết nối lại (stream cũ không tự phục hồi).
  3. Không cần khởi động lại Forwarder cho lần kiểm tra kế tiếp, nhưng cũng không có lệnh nào "mở chặn" từ phía Forwarder, mọi thứ đi theo trạng thái device ở Registry.
  4. Nếu token bị sai/thừa ở client: kiểm tra client gửi metadata x-device-token đúng token của chính nó.

Xác minh:

bash
grep "disabled by supervisor guard" logs/default.log | tail -5
# các dòng ngừng xuất hiện sau khi device chuyển sang Active

# thử lại kết nối gRPC từ client: không còn permission_denied

Port, tài nguyên và container ​

Port bị chiếm hoặc không mở ​

Triệu chứng: Đã khai section server đầy đủ nhưng ss/netstat không thấy port LISTEN, hoặc server khác báo address already in use. Hay gặp nhất với cổng 8080 (proxy), rất nhiều service web mặc định dùng 8080.

Nguyên nhân:

  1. Port đã bị process khác chiếm trước.
  2. Cổng đặc quyền (514, 162) nhưng process không chạy quyền root nên không bind được.
  3. Thiếu section server, xem Thiếu section server.

Giải pháp:

  1. Tìm process đang giữ port:
bash
sudo ss -tulnp | grep -E ':(514|162|1883|50051|8080|18080)'
  1. Dừng process kia, hoặc đổi địa chỉ bind của Forwarder trong section tương ứng (proxy_server.addr, rsyslog_server.udp_addr / tcp_addr, snmp_server.trap_addr, mqtt_server.server.listen, grpc_server.listen_addr, registry.http_server.listen_addr), xem Embedded servers.
  2. Với 514/162: chạy bằng quyền root (chế độ service đã là root).
  3. Khởi động lại service (mọi section server không hot-reload).

Xác minh:

bash
sudo ss -tulnp | grep -E ':(514|162|1883|50051|8080|18080)'
# kỳ vọng: dòng LISTEN/udp gắn với process blackhole-fwd
powershell
netstat -an | findstr ":8080"
# kỳ vọng: dòng LISTENING

Pipeline bị tạm dừng bởi resource guard ​

Triệu chứng: Forwarder vẫn là process sống nhưng ngừng nhận, xử lý và gửi đi một thời gian. Trong log:

PAUSING ORCHESTRATOR due to resource constraints

Nguyên nhân: CPU hoặc memory vượt threshold_percentage (mặc định 80%) liên tục hết sustained_secs (mặc định 60 giây). Khi đó pipeline được tạm dừng: collector, transform, shipper dừng và queue được flush, event không bị drop và process không thoát. Disk mặc định tắt (ngưỡng 101.0).

Giải pháp:

  1. Xem mức sử dụng thực tế (top trên Linux, Task Manager trên Windows) và xử lý nguyên nhân (process chiếm tài nguyên, burst sự kiện…).
  2. Hoặc nâng resources_threshold.cpu.threshold_percentage / memory.threshold_percentage rồi khởi động lại (ngưỡng chỉ đọc lúc khởi động).
  3. Không cần can thiệp nếu máy vừa hồi phục, pipeline tự chạy lại.
  4. Kiểm tra hàng đợi: event chưa gửi nằm trong database blackhole-fwd.db, sẽ được gửi tiếp khi resume hoặc ở lần khởi động sau.

Xác minh:

bash
grep -E "PAUSING ORCHESTRATOR|RESUMING ORCHESTRATOR" logs/default.log | tail -10
# kỳ vọng: sau khi resource hạ, có dòng
# "RESUMING ORCHESTRATOR - resources have stabilized"

pgrep -x blackhole-fwd
# process vẫn tồn tại suốt thời gian bị tạm dừng

Container không exec vào được ​

Triệu chứng: docker exec -it blackhole-fwd sh (hoặc bash, cat, ps) thất bại, ví dụ:

OCI runtime exec failed: exec failed: unable to start container process: exec: "sh": executable file not found in $PATH

Nguyên nhân: Image ghcr.io/gcsclabs/blackhole-forwarder build trên nền distroless: không có shell, không có package manager, không có tool gỡ rối, và chạy bằng user nonroot (uid 65532). Đây là hành vi bình thường, không phải lỗi.

Giải pháp:

  1. Đọc log bằng docker logs:
bash
docker logs -f blackhole-fwd
docker logs --tail 200 blackhole-fwd
  1. Mount volume tại /home/nonroot khi chạy container, rồi đọc file logs/default.log và database ngay trên host.
  2. Vẫn có thể exec thẳng executable (không cần shell):
bash
docker exec blackhole-fwd /usr/local/bin/blackhole-fwd --version
  1. Muốn thao tác shell thì dùng image build từ source với base khác (developer image), image sản phẩm không kèm shell.

Xác minh:

bash
docker logs --tail 50 blackhole-fwd
# có log runtime, ví dụ "Orchestrator started successfully"

docker exec blackhole-fwd /usr/local/bin/blackhole-fwd --version
# in ra blackhole-fwd <phiên bản>

Xem thêm ​

Released under the MIT License.

Copyright © 2024 G-BlackHole