G-BlackHole Documentation

Appearance

Yêu cầu ​

  • Đã cài blackhole-agt, xem Cài đặt.
  • Windows: quyền Administrator cho bước cài service. Linux: quyền root và systemd hoặc OpenRC cho bước cài service.
  • Kiến trúc x86_64.
  • Không cần backend nào cho ví dụ này: pipeline ghi sự kiện ra file ngay trên máy.

Trong hướng dẫn này, $AgentDir (Windows) và $AGENT_DIR (Linux) là thư mục chứa executable. Hãy đổi biến này cho đúng với máy bạn:

  • Cài bằng MSI: C:\Program Files\blackhole-agt\bin
  • Cài bằng bộ cài đặt: %USERPROFILE%\.cargo\bin (Windows) hoặc $HOME/.cargo/bin (Linux)
  • Cài thủ công: thư mục bạn đã copy binary vào

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

Ví dụ dưới đây dùng source file đọc file log và sink file ghi ra ./debug-events/. Không cần Kafka, MQTT hay gRPC nên bạn kiểm tra được đầu ra ngay trên máy.

Windows ​

powershell
$AgentDir = "C:\Program Files\blackhole-agt\bin"   # đổi thành thư mục chứa blackhole-agt.exe
$Config   = Join-Path $AgentDir "blackhole-agt.yml"

# Tạo sẵn log mẫu để collector có dữ liệu ngay khi khởi động
New-Item -ItemType Directory -Path "$AgentDir\sample-logs" -Force | Out-Null
Set-Content -Path "$AgentDir\sample-logs\test.log" -Value "test event 1"

@"
sources:
  sample_logs:
    type: file
    includes:
      - ./sample-logs/*.log
    tail: false
sinks:
  local_debug:
    type: file
    inputs: ["*"]
    path: ./debug-events/
    max_size_mb: 10
    max_files: 5
"@ | Set-Content -Path $Config -Encoding utf8

Linux ​

bash
AGENT_DIR="$HOME/.cargo/bin"   # đổi thành thư mục chứa binary
CONFIG="$AGENT_DIR/blackhole-agt.yml"

# Tạo sẵn log mẫu để collector có dữ liệu ngay khi khởi động
mkdir -p "$AGENT_DIR/sample-logs"
echo "test event 1" > "$AGENT_DIR/sample-logs/test.log"

cat > "$CONFIG" <<'EOF'
sources:
  sample_logs:
    type: file
    includes:
      - ./sample-logs/*.log
    tail: false
sinks:
  local_debug:
    type: file
    inputs: ["*"]
    path: ./debug-events/
    max_size_mb: 10
    max_files: 5
EOF

Xác minh ​

powershell
# Windows
Get-Content $Config
bash
# Linux
cat "$CONFIG"

Kết quả mong đợi: nội dung YAML vừa ghi, với type: file ở cả sources và sinks.

📝
Agent có cấu hình mẫu từ Registry hay không đều được. Nếu dùng Registry, bạn lấy cấu hình đã đăng ký bằng `blackhole-agt --config $Config configure pull`. Còn khi viết tay, lấy ví dụ trong [Cấu hình](./configuration).
💡
Chạy `blackhole-agt --config $Config configure schema` để tạo file `config.jsonschema` ngay cạnh file cấu hình, dùng cho trình soạn thảo báo lỗi khi bạn sửa YAML.

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

Windows ​

powershell
cd $AgentDir
.\blackhole-agt.exe --config $Config --verbose start

Linux ​

bash
cd "$AGENT_DIR"
./blackhole-agt --config "$CONFIG" --verbose start

Agent khởi động và đọc file cấu hình ngay. Nếu file không tồn tại ở đường dẫn truyền cho --config, tiến trình dừng với lỗi Failed to read file for hashing: <tên file>.

Dừng thử bằng Ctrl+C.

Xác minh ​

Mở một terminal khác, chạy:

powershell
# Windows
cd $AgentDir
Get-ChildItem .\debug-events
Get-Content .\debug-events\* -TotalCount 5
bash
# Linux
cd "$AGENT_DIR"
ls debug-events/
head -n 5 debug-events/*

Kết quả mong đợi: thư mục debug-events/ được tạo và có file chứa test event 1 bạn vừa ghi ở Bước 1.

Bước 3: Xác thực với Registry (tùy chọn) ​

Bỏ qua bước này nếu bạn chạy Agent hoàn toàn local. Nếu dùng Registry, thứ tự bắt buộc là: tạo cấu hình có registry: → auth → cài service.

⚠️
Nếu cấu hình đã có section `registry:` nhưng bạn chưa chạy `auth`, Agent vẫn khởi động bình thường nhưng **không collector nào được chạy**, với log `Device is not active, no collectors will be started`.

Thêm registry: vào file cấu hình (ít nhất là api_url):

Windows ​

powershell
Add-Content -Path $Config -Value @"

registry:
  api_url: "https://<registry-host>"
"@

.\blackhole-agt.exe --config $Config auth --key "<API key>"

Linux ​

bash
cat >> "$CONFIG" <<'EOF'

registry:
  api_url: "https://<registry-host>"
EOF

./blackhole-agt --config "$CONFIG" auth --key "<API key>"

Xác minh ​

Lệnh auth hoàn tất mà không báo lỗi: thiết bị được đăng ký và cấu hình local được đẩy lên Registry.

  • Nếu thiếu registry.api_url, lệnh dừng với No registry configured.
  • Chạy configure push trước khi auth sẽ dừng với device token not available, you need to authenticate first.

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

⚠️
`--config` truyền lúc `service install` không được lưu lại. Service được ghi nhận đúng bằng chuỗi `<đường dẫn executable> --service --service-name blackhole-agt` và tự tìm cấu hình trong **thư mục chứa executable**, theo thứ tự: `blackhole-agt.yml`, rồi `config.yml`, rồi `config.yaml`.

Đây là nguyên nhân phổ biến nhất của tình trạng "service chạy nhưng không thu thập gì": file cấu hình nằm sai chỗ. Hãy đặt blackhole-agt.yml cạnh executable như Bước 1 đã làm.

service install khởi động service ngay lập tức, nên không cần chạy service start thêm.

Windows ​

powershell
cd $AgentDir
.\blackhole-agt.exe service install

Linux ​

bash
cd "$AGENT_DIR"
sudo ./blackhole-agt service install

Lệnh ghi file unit /etc/systemd/system/blackhole-agt.service, đặt WorkingDirectory là thư mục chứa executable, Restart=on-failure và khởi động cùng hệ thống.

Nếu service đã tồn tại, lệnh dừng với Service already exists. Use --force to overwrite. — chạy lại với service install --force để ghi đè.

Xác minh ​

powershell
# Windows
Get-Service -Name "blackhole-agt"
cd $AgentDir
.\blackhole-agt.exe service status
bash
# Linux
systemctl status blackhole-agt
cd "$AGENT_DIR"
sudo ./blackhole-agt service status

Kết quả mong đợi: trạng thái service là Running (Windows) hoặc active (running) (Linux).

Xác minh ​

Windows ​

powershell
cd $AgentDir

# Trạng thái service
Get-Service -Name "blackhole-agt"

# Log của service
Get-Content .\logs\default.log -Tail 20
Get-Content .\logs\default-error.log -Tail 20

# Dữ liệu đã thu thập
Get-Content .\debug-events\* -TotalCount 5

Linux ​

bash
cd "$AGENT_DIR"

# Trạng thái service
systemctl status blackhole-agt

# Log của service
tail -n 20 logs/default.log
tail -n 20 logs/default-error.log

# Dữ liệu đã thu thập
head -n 5 debug-events/*

Kết quả mong đợi: service ở trạng thái chạy, logs/default.log có dòng log mới, và file trong debug-events/ chứa test event 1.

📝
Agent **không ghi log của nó vào Windows Event Log** (Event Viewer), nên đừng tìm log Agent ở đó — kể cả khi bạn đã bật collector `windows_event`, collector đó chỉ *đọc* Event Log của hệ thống chứ không phải nơi Agent ghi log. Log của Agent chỉ nằm ở `logs/default.log` và `logs/default-error.log`, tương đối so với thư mục chứa executable. Ở chế độ service, stdout bị tắt nên `journalctl -u blackhole-agt` gần như rỗng, hãy đọc file log.
📝
Nếu cấu hình trỏ tới Registry mà Registry không liên lạc được, Agent ghi warning rồi tiếp tục chạy theo cấu hình local, không thoát.

Bước tiếp theo ​

Released under the MIT License.

Copyright © 2024 G-BlackHole