G-BlackHole Documentation

Appearance

Installing BlackHole Search ​

BlackHole Search cung cấp giải pháp tích hợp đầy đủ để khám phá, tìm hiểu và truy vấn dữ liệu quan sát của bạn một cách trực quan. Bạn có thể cài đặt BlackHole Search với bất kỳ tùy chọn nào sau đây:

  • Docker
  • Tarball
  • RPM
  • Debian
  • Helm
  • Windows

Browser compatibility ​

BlackHole Search hỗ trợ các trình duyệt web sau:

  • Chrome
  • Firefox
  • Safari
  • Edge (Chromium) Các trình duyệt khác dựa trên Chromium cũng có thể hoạt động. Internet Explorer và Microsoft Edge Legacy không được hỗ trợ.

Node.js compatibility ​

BlackHole Search yêu cầu cài đặt Node.js runtime binary để chạy. Một gói cài đặt có sẵn trong các gói phân phối có sẵn trên trang tải xuống BlackHole. Để sử dụng tệp nhị phân thời gian chạy Node.js khác với tệp có trong các gói phân phối, hãy làm theo các bước sau:

  1. Tải xuống và cài đặt Node.js; các phiên bản tương thích là >=14.20.1 <19
  2. Đặt đường dẫn cài đặt tới biến môi trường NODE_HOME hoặc NODE_OSD_HOME.
	- On UNIX, if Node.js is installed to /usr/local/nodejs and the runtime binary is /usr/local/nodejs/bin/node:
export NODE_HOME=/usr/local/nodejs
	- If Node.js is installed using NVM and the runtime binary is /Users/user/.nvm/versions/node/v18.19.0/bin/node:
export NODE_HOME=/Users/user/.nvm/versions/node/v18.19.0 # or, if NODE_HOME is used for something else: export NODE_OSD_HOME=/Users/user/.nvm/versions/node/v18.19.0
	- On Windows, if Node.js is installed to C:\Program Files\nodejs and the runtime binary is C:\Program Files\nodejs\node.exe:
set "NODE_HOME=C:\Program Files\nodejs"
# or using PowerShell:
$Env:NODE_HOME = 'C:\Program Files\nodejs'

Tham khảo tài liệu của hệ điều hành để thực hiện thay đổi liên tục đối với các biến môi trường. Tập lệnh khởi động BlackHole Search, bin/blackhole-search, sẽ tìm kiếm tệp nhị phân thời gian chạy Node.js bằng NODE_OSD_HOME, sau đó là NODE_HOME, trước khi sử dụng các tệp nhị phân đi kèm với các gói phân phối. Nếu không tìm thấy tệp nhị phân thời gian chạy Node.js khả dụng, tập lệnh khởi động sẽ cố gắng tìm một tệp trong PATH trên toàn hệ thống trước khi thất bại.

Configuration ​

Để tìm hiểu cách cấu hình TLS cho BlackHole Search, hãy xem Configure TLS.

Run BlackHole Search using Docker and Docker Compose ​

Bạn có thể sử dụng Docker hoặc Docker Compose để chạy BlackHole Search. Phương pháp Docker Compose dễ dàng hơn vì bạn có thể định nghĩa toàn bộ cấu hình trong một tệp duy nhất.

Chạy BlackHole Search bằng Docker ​

Nếu bạn đã xác định mạng của mình bằng docker network, hãy tạo bh-net và khởi động BlackHole bằng lệnh sau:

docker run -d --name blackhole-node -p 9200:9200 -p 9600:9600 --network bh-net -e "discovery.type=single-node" -e "BLACKHOLE_INITIAL_ADMIN_PASSWORD=<admin_password>" ghcr.io/gcsclabs/blackhole-backend:latest
  1. Tạo tệp cấu hình blackhole_search.yml:
server.name: blackhole_search
server.host: "0.0.0.0"
server.customResponseHeaders : { "Access-Control-Allow-Credentials" : "true" }
# Disabling HTTPS on BlackHole Search
server.ssl.enabled: false
blackhole.hosts: ["https://blackhole-node:9200"] # Using the BlackHole container name
blackhole.ssl.verificationMode: none
blackhole.username: kibanaserver
blackhole.password: kibanaserver
blackhole.requestHeadersWhitelist: ["securitytenant","Authorization"]

# Multitenancy
blackhole_security.multitenancy.enabled: true
blackhole_security.multitenancy.tenants.preferred: ["Private", "Global"]
blackhole_security.readonly_mode.roles: ["kibana_read_only"]
  1. Thực hiện lệnh sau để bắt đầu BlackHole Search
docker run -d --name bhd \
--network bh-net \
-p 3000:3000 \
-v ./blackhole_search.yml:/usr/share/blackhole-search/config/blackhole_search.yml \
ghcr.io/gcsclabs/siem-dashboards:latest

Chạy BlackHole Search bằng Docker Compose ​

Sử dụng các bước sau để chạy BlackHole Search bằng Docker Compose:

  1. Tạo tệp docker-compose.yml phù hợp với môi trường của bạn. Tệp mẫu bao gồm BlackHole Search có sẵn trên trang cài đặt BlackHole Docker. Bạn có thể truyền tệp blackhole_search.yml tùy chỉnh vào vùng chứa trong tệp Docker Compose. Để biết thêm thông tin, hãy xem Ví dụ Docker Compose hoàn chỉnh với cấu hình tùy chỉnh.
  2. Tạo tệp blackhole_search.yml:
server.name: blackhole_search
server.host: "0.0.0.0"
server.customResponseHeaders : { "Access-Control-Allow-Credentials" : "true" }

# Disabling HTTPS on BlackHole Search
server.ssl.enabled: false

blackhole.ssl.verificationMode: none
blackhole.username: kibanaserver
blackhole.password: kibanaserver
blackhole.requestHeadersWhitelist: ["securitytenant","Authorization"]

# Multitenancy
blackhole_security.multitenancy.enabled: true
blackhole_security.multitenancy.tenants.preferred: ["Private", "Global"]
blackhole_security.readonly_mode.roles: ["kibana_read_only"]

Thiết lập blackhole.hosts phải được cấu hình nếu bạn không truyền nó dưới dạng biến môi trường. Để biết ví dụ về cách cấu hình thiết lập này, hãy xem. Ví dụ Docker Compose hoàn chỉnh với cấu hình tùy chỉnh. 3. Chạy docker compose up Đợi các container khởi động. Sau đó, xem tài liệu Tìm kiếm BlackHole 4. Khi hoàn tất, hãy chạy docker compose down.

Chạy BlackHole Search bằng tarball ​

  1. Tải xuống tarball tại đây.
  2. Giải nén tệp TAR vào một thư mục và chuyển đến thư mục đó:
# x64
tar -zxf blackhole-dashboards-linux-x64.tar.gz
cd blackhole-dashboards
  1. Nếu muốn, hãy sửa đổi config/blackhole_search.yml, sau đây là config demo.
bash
# ============================================================
# Blackhole Dashboards – Demo Configuration File
# ============================================================

# ------------------------------------------------------------
# Server connection settings
# ------------------------------------------------------------
server.host: "0.0.0.0"
server.port: 3000

# ------------------------------------------------------------
# Enable HTTPS for the Dashboards server
# ------------------------------------------------------------
server.ssl.enabled: true
server.ssl.certificate: /path/to/certs/client.pem
server.ssl.key: /path/to/certs/client-key.pem

# ------------------------------------------------------------
# Backend (Blackhole) connection settings
# ------------------------------------------------------------
blackhole.hosts:
  - "https://localhost:9200"

blackhole.username: "kibanaserver"
blackhole.password: "kibanaserver"

# ------------------------------------------------------------
# TLS / SSL settings for backend connection
# ------------------------------------------------------------
blackhole.ssl.verificationMode: full
blackhole.ssl.certificateAuthorities:
  - /path/to/certs/root-ca.pem
blackhole.ssl.certificate: /path/to/certs/client.pem
blackhole.ssl.key: /path/to/certs/client-key.pem

# Ignore version mismatch between Dashboards and backend
blackhole.ignoreVersionMismatch: true

# ------------------------------------------------------------
# Allowed request headers
# ------------------------------------------------------------
blackhole.requestHeadersAllowlist:
  - securitytenant
  - Authorization

# ------------------------------------------------------------
# Security plugin settings
# ------------------------------------------------------------
blackhole_security.cookie.secure: true

# Multi-tenancy configuration
blackhole_security.multitenancy.enabled: true
blackhole_security.multitenancy.tenants.enable_global: true
blackhole_security.multitenancy.tenants.enable_private: true
blackhole_security.multitenancy.tenants.preferred:
  - Private
  - Global
blackhole_security.multitenancy.enable_filter: false

# Read-only roles
blackhole_security.readonly_mode.roles:
  - kibana_read_only

# Login UI customization
blackhole_security.ui.basicauth.login.title: "Login into BlackHole Dashboard"

# ------------------------------------------------------------
# UI / UX settings
# ------------------------------------------------------------
home.disableWelcomeScreen: true

# ------------------------------------------------------------
# External services (demo example)
# ------------------------------------------------------------
device_management.api.base_url: "http://blackhole-devices-management:3000"

# ------------------------------------------------------------
# Branding configuration
# ------------------------------------------------------------
blackholeDashboards.branding:
  applicationTitle: "Blackhole"
  useExpandedHeader: false
  1. Run BlackHole Search:
./bin/blackhole-search

Cấu hình TLS cho Blackhole Dashboards ​

Theo mặc định, để thuận tiện cho việc thử nghiệm và bắt đầu sử dụng, Blackhole Dashboards chạy trên HTTP.
Để bật TLS cho HTTPS, hãy cập nhật các thiết lập sau trong file blackhole_dashboards.yml.

Các thiết lập TLS ​

Thiết lậpMô tả
server.ssl.enabledBật giao tiếp SSL giữa máy chủ Blackhole Dashboards và trình duyệt web của người dùng. Đặt true cho HTTPS hoặc false cho HTTP.
server.ssl.supportedProtocolsChỉ định danh sách các giao thức TLS được hỗ trợ. Các giá trị có thể gồm TLSv1, TLSv1.1, TLSv1.2, TLSv1.3. Mặc định: ['TLSv1.1', 'TLSv1.2', 'TLSv1.3'].
server.ssl.cipherSuitesChỉ định danh sách các bộ mã TLS. Không bắt buộc.
server.ssl.certificateKhi server.ssl.enabled: true, chỉ định đường dẫn đầy đủ tới chứng chỉ máy chủ PEM hợp lệ cho Blackhole Dashboards.
server.ssl.keyKhi server.ssl.enabled: true, chỉ định đường dẫn đầy đủ tới khóa của chứng chỉ máy chủ.
server.ssl.keyPassphraseMật khẩu của khóa. Bỏ qua nếu khóa không có mật khẩu. Không bắt buộc.
server.ssl.keystore.pathSử dụng file JKS hoặc PKCS12/PFX thay cho chứng chỉ và khóa PEM.
server.ssl.keystore.passwordMật khẩu của keystore. Bắt buộc.
server.ssl.clientAuthenticationChế độ xác thực TLS phía client: none, optional, hoặc required. Mặc định: none.
server.ssl.certificateAuthoritiesĐường dẫn đầy đủ tới một hoặc nhiều chứng chỉ CA (dạng mảng) dùng cho xác thực client. Bắt buộc nếu clientAuthentication là optional hoặc required.
server.ssl.truststore.pathSử dụng trust store JKS hoặc PKCS12/PFX thay cho chứng chỉ CA dạng PEM.
server.ssl.truststore.passwordMật khẩu của trust store. Bắt buộc.
blackhole.ssl.verificationModeThiết lập giao tiếp giữa Blackhole và Blackhole Dashboards. Giá trị: full, certificate, none. Khuyến nghị dùng full.
blackhole.ssl.certificateAuthoritiesĐường dẫn đầy đủ tới một hoặc nhiều chứng chỉ CA tạo thành chuỗi tin cậy cho cụm Blackhole.
blackhole.ssl.truststore.pathSử dụng trust store JKS hoặc PKCS12/PFX thay cho chứng chỉ CA dạng PEM.
blackhole.ssl.truststore.passwordMật khẩu của trust store. Bắt buộc.
blackhole.ssl.alwaysPresentCertificateNếu true, luôn gửi chứng chỉ client tới cụm Blackhole (cần thiết khi bật mTLS). Mặc định: false.
blackhole.ssl.certificateKhi alwaysPresentCertificate: true, chỉ định đường dẫn tới chứng chỉ client cho cụm Blackhole.
blackhole.ssl.keyKhi alwaysPresentCertificate: true, chỉ định đường dẫn tới khóa của chứng chỉ client.
blackhole.ssl.keyPassphraseMật khẩu của khóa. Bỏ qua nếu khóa không có mật khẩu. Không bắt buộc.
blackhole.ssl.keystore.pathSử dụng keystore JKS hoặc PKCS12/PFX thay cho chứng chỉ và khóa PEM.
blackhole.ssl.keystore.passwordMật khẩu của keystore. Bắt buộc.
blackhole_security.cookie.secureNếu bật TLS cho Blackhole Dashboards, đặt true. Với HTTP, đặt false.
blackhole_security.session.keepaliveXác định TTL của phiên có được gia hạn sau mỗi hoạt động người dùng hay không. Mặc định: true.
blackhole_security.session.ttlThời gian tồn tại (TTL) của phiên người dùng, tính bằng mili giây. Mặc định: 3600000 (1 giờ).

Ví dụ cấu hình demo ​

yaml
# ============================================================
# Blackhole Dashboards – Demo Configuration File
# ============================================================

# ------------------------------------------------------------
# Server connection settings
# ------------------------------------------------------------
server.host: "0.0.0.0"
server.port: 3000

# ------------------------------------------------------------
# Enable HTTPS for the Dashboards server
# ------------------------------------------------------------
server.ssl.enabled: true
server.ssl.certificate: /path/to/certs/client.pem
server.ssl.key: /path/to/certs/client-key.pem

# ------------------------------------------------------------
# Backend (Blackhole) connection settings
# ------------------------------------------------------------
blackhole.hosts:
  - "https://localhost:9200"

blackhole.username: "kibanaserver"
blackhole.password: "kibanaserver"

# ------------------------------------------------------------
# TLS / SSL settings for backend connection
# ------------------------------------------------------------
blackhole.ssl.verificationMode: full
blackhole.ssl.certificateAuthorities:
  - /path/to/certs/root-ca.pem
blackhole.ssl.certificate: /path/to/certs/client.pem
blackhole.ssl.key: /path/to/certs/client-key.pem

# Ignore version mismatch between Dashboards and backend
blackhole.ignoreVersionMismatch: true

# ------------------------------------------------------------
# Allowed request headers
# ------------------------------------------------------------
blackhole.requestHeadersAllowlist:
  - securitytenant
  - Authorization

# ------------------------------------------------------------
# Security plugin settings
# ------------------------------------------------------------
blackhole_security.cookie.secure: true

# Multi-tenancy configuration
blackhole_security.multitenancy.enabled: true
blackhole_security.multitenancy.tenants.enable_global: true
blackhole_security.multitenancy.tenants.enable_private: true
blackhole_security.multitenancy.tenants.preferred:
  - Private
  - Global
blackhole_security.multitenancy.enable_filter: false

# Read-only roles
blackhole_security.readonly_mode.roles:
  - kibana_read_only

# Login UI customization
blackhole_security.ui.basicauth.login.title: "Login into BlackHole Dashboard"

# ------------------------------------------------------------
# UI / UX settings
# ------------------------------------------------------------
home.disableWelcomeScreen: true

# ------------------------------------------------------------
# External services (demo example)
# ------------------------------------------------------------
device_management.api.base_url: "http://blackhole-devices-management:3000"

# ------------------------------------------------------------
# Branding configuration
# ------------------------------------------------------------
blackholeDashboards.branding:
  applicationTitle: "Blackhole"
  useExpandedHeader: false

Docker ​

Nếu bạn sử dụng tùy chọn cài đặt bằng Docker, bạn có thể truyền một file blackhole_dashboards.yml tùy chỉnh vào container.
Tham khảo thêm trong tài liệu cài đặt Docker.

Truy cập ​

Sau khi bật các thiết lập trên và khởi động ứng dụng, bạn có thể truy cập Blackhole Dashboards tại:

https://localhost:3000

Nếu sử dụng chứng chỉ tự ký, trình duyệt có thể hiển thị cảnh báo bảo mật.
Để tránh cảnh báo (hoặc vấn đề tương thích trình duyệt), nên sử dụng chứng chỉ được cấp bởi một CA đáng tin cậy.

Cấu hình License ​

License là tệp có định dạng .license được cung cấp bởi quản trị viên. License là bắt buộc để BlackHole Search có thể thực hiện các thao tác insert dữ liệu vào hệ thống.

Khi nào cần upload License ​

Bạn cần upload License trong các trường hợp sau:

  • License chưa được cài đặt
  • License đã hết hạn
  • Cần thay đổi License hiện tại
⚠️
Nếu không có License hoặc License đã hết hạn, bạn sẽ không thể thực hiện thao tác insert dữ liệu vào hệ thống.

Các bước upload License ​

Thực hiện theo các bước sau để upload License:

  1. Truy cập License Management: Điều hướng đến đường dẫn app/license-management trong giao diện BlackHole Search.

  2. Mở hộp thoại Add License: Bấm vào nút "+ Add License" ở góc trên bên phải.

  3. Chọn tệp License:

    • Kéo thả tệp License vào vùng upload, hoặc
    • Bấm vào vùng "Choose file or drag & drop" để chọn tệp từ máy tính

  4. Xác nhận upload: Bấm nút "Upload License" để hoàn tất.

Add License

Nếu upload thành công, hệ thống sẽ hiển thị thông báo "License uploaded successfully".

Kết nối với Device Management ​

Device Management là dịch vụ quản lý tập trung cho xác thực và cấu hình của các Agent và Forwarder. Để BlackHole Search có thể tương tác với Device Management, bạn cần cấu hình URL của dịch vụ trong file blackhole_search.yml.

Cấu hình kết nối ​

Thêm hoặc cập nhật thiết lập sau trong file blackhole_search.yml:

yaml
# ------------------------------------------------------------
# External services - Device Management
# ------------------------------------------------------------
device_management.api.base_url: "http://blackhole-devices-management:3000"

Trong đó:

  • blackhole-devices-management là tên container hoặc hostname của dịch vụ Device Management
  • 3000 là cổng mặc định của Device Management API

Lưu ý về mạng ​

Khi sử dụng Docker, đảm bảo BlackHole Search và Device Management cùng nằm trong một Docker network để có thể giao tiếp với nhau. Nếu sử dụng Docker Compose, các service sẽ tự động nằm trong cùng một network.

Để biết cách cài đặt Device Management, hãy xem Hướng dẫn cài đặt Device Management.

Chạy BlackHole Dashboards như một dịch vụ với systemd ​

Tài liệu này hướng dẫn chi tiết cách chạy BlackHole Dashboards như một dịch vụ nền (daemon) được quản lý bởi systemd trên Linux.
Sau khi hoàn tất, bạn có thể quản lý BlackHole Dashboards bằng các lệnh chuẩn:

bash
systemctl start blackhole-dashboards
systemctl stop blackhole-dashboards
systemctl status blackhole-dashboards
systemctl enable blackhole-dashboards

Hướng dẫn này giả định BlackHole Dashboards được cài đặt bằng tarball tại:

/opt/blackhole-dashboards-3.1.0-SNAPSHOT-linux-x64

Nếu bạn cài ở vị trí khác, hãy đổi toàn bộ đường dẫn tương ứng.

Giả định & phạm vi ​

ℹ️
"Giả định" - BlackHole Dashboards được cài bằng **tarball** - Hệ điều hành sử dụng **systemd** - BlackHole backend đã chạy và truy cập được
⚠️
Không khuyến nghị chạy BlackHole Dashboards bằng tarball trong production. 
Với production:
- Dùng Docker / Kubernetes
- Hoặc triển khai phía sau reverse proxy (Nginx)

Tổng quan kiến trúc ​

mermaid
flowchart LR
systemd -->|start/stop| Dashboards
Dashboards -->|HTTP/HTTPS| BlackHole
Dashboards --> Browser
  • Dashboards là Node.js application
  • systemd quản lý vòng đời tiến trình
  • Log được ghi vào journalctl
  • Không yêu cầu quyền root

Bước 0: Di chuyển BlackHole Dashboards vào /opt ​

Giả sử bạn đã giải nén tarball tại:

~/blackhole-dashboards-3.1.0-SNAPSHOT-linux-x64/

Di chuyển vào vị trí chuẩn:

bash
sudo mv ~/blackhole-dashboards-3.1.0-SNAPSHOT-linux-x64 /opt/blackhole-dashboards

Bước 1: Tạo user hệ thống cho Dashboards ​

📝
Dashboards **nên dùng chung user `blackhole`** với backend để: - đơn giản permission - dễ quản lý log và config
bash
sudo adduser \
  --system \
  --shell /bin/bash \
  -U \
  --no-create-home \
  blackhole

Bước 2: Gán quyền cho thư mục Dashboards ​

bash
sudo chown -R blackhole:blackhole /opt/blackhole-dashboards

Bước 3: Tạo file systemd service ​

bash
sudo vi /etc/systemd/system/blackhole-dashboards.service

Bước 4: Cấu hình blackhole-dashboards.service ​

Toàn bộ nội dung file ​

ini
[Unit]
Description=BlackHole Dashboards
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/blackhole-dashboards
ExecStart=/opt/blackhole-dashboards/bin/blackhole-dashboards

User=blackhole
Group=blackhole

Environment=NODE_ENV=production

StandardOutput=journal
StandardError=inherit

Restart=on-failure
RestartSec=10

LimitNOFILE=65535
TimeoutStartSec=60

[Install]
WantedBy=multi-user.target

Giải thích chi tiết ​

[Unit] ​

Cấu hìnhÝ nghĩa
network-online.targetĐảm bảo backend sẵn sàng

[Service] – Node.js app ​

Cấu hìnhÝ nghĩa
Type=simpleNode.js chạy foreground
ExecStartScript khởi động Dashboards
Restart=on-failureTự restart khi crash
NODE_ENV=productionChế độ production

Log xem bằng:

bash
journalctl -u blackhole-dashboards -f

User & Permission ​

Dashboards:

  • không cần root
  • chỉ cần quyền đọc config và bind port (>1024)

Bước 5: Reload systemd ​

bash
sudo systemctl daemon-reload

Bước 6: Enable service ​

bash
sudo systemctl enable blackhole-dashboards.service

Bước 7: Khởi động Dashboards ​

bash
sudo systemctl start blackhole-dashboards

Bước 8: Kiểm tra trạng thái & log ​

=== "Trạng thái" bash systemctl status blackhole-dashboards

=== "Log realtime" bash journalctl -u blackhole-dashboards -f

Checklist khi Dashboards không start ​

  • [ ] BlackHole backend đang chạy
  • [ ] blackhole_dashboards.yml cấu hình đúng endpoint
  • [ ] Port 3000 chưa bị chiếm
  • [ ] Node.js binary tồn tại trong /bin
  • [ ] Quyền thư mục đúng

Ghi chú cho production ​

📝

Không áp dụng cho tarball.

  • Chạy Dashboards phía sau Nginx
  • Bật HTTPS
  • Bật authentication
  • Giới hạn memory Node.js
  • Dùng Docker/Kubernetes nếu có thể

Released under the MIT License.

Copyright © 2024 G-BlackHole