​
Quick Start BlackHole Core

Phần này hướng dẫn cài đặt BlackHole Single Node
Tài liệu hướng dẫn cho bản cài Tarball.

​
1. Yêu cầu tối thiểu

Yêu cầu mỗi VM tối thiểu 2GB RAM, 50 GB Disk. Danh sách các port bao gồm:
PortThành phần
9200BlackHole REST API
9300Giao tiếp giữa các node (internal), cross cluster search
9600Performance Analyzer

​
2. Cài đặt BlackHole Core (Ubuntu 24.04)

​
Bước 1: Tải và giải nén BlackHole Core

Sử dụng câu lệnh sau để tải xuống file cài đặt: 
sudo wget https://docs-blackhole.glabs.one/downloads/blackhole-core/blackhole-core-linux.tar.gz -o /opt/blackhole.tar.gz
Giải nén: 
sudo cd /opt
sudo tar -xvf blackhole.tar.gz
sudo mv blackhole-3.1.0 blackhole

​
Bước 2: Cấu hình thiết lập hệ thống

Trên tất cả các VM thực hiện:
  1. Tắt swap để cải thiện hiệu suất:
sudo swapoff -a
sudo sed -i '/ swap / s/^/#/' /etc/fstab
  1. Tăng số lượng memory maps cho BlackHole:
sudo echo "vm.max_map_count=262144" >> /etc/sysctl.conf
Reload và xác minh: 
# Reload cấu hình
sudo sysctl -p

# Xác minh thay đổi
cat /proc/sys/vm/max_map_count
  1. Cấu hình JVM heap (nên set RAM bằng 1/2 RAM của VM):
sed -i 's/^-Xms1g/-Xms2g/' /opt/blackhole/config/jvm.options
sed -i 's/^-Xmx1g/-Xmx2g/' /opt/blackhole/config/jvm.options

​
Bước 3: Gen Cert

Script sau sẽ sinh cert 
#!/bin/bash
set -e

BASE_DIR="$(pwd)/certs"
DAYS=3650

NODES=(
  "blackhole-aio"
)

mkdir -p ${BASE_DIR}/{ca,admin,nodes}

echo "[1/6] Create Root CA..."
openssl genrsa -out ${BASE_DIR}/ca/root-ca-key.pem 4096
openssl req -x509 -new -nodes \
  -key ${BASE_DIR}/ca/root-ca-key.pem \
  -sha256 -days ${DAYS} \
  -out ${BASE_DIR}/ca/root-ca.pem \
  -subj "/C=VN/O=BlackHole/OU=PKI/CN=BlackHole-Root-CA"

echo "[2/6] Create Admin certificate..."
openssl genrsa -out ${BASE_DIR}/admin/admin-key.pem 4096
openssl req -new \
  -key ${BASE_DIR}/admin/admin-key.pem \
  -out ${BASE_DIR}/admin/admin.csr \
  -subj "/C=VN/O=BlackHole/OU=Security/CN=admin"

openssl x509 -req \
  -in ${BASE_DIR}/admin/admin.csr \
  -CA ${BASE_DIR}/ca/root-ca.pem \
  -CAkey ${BASE_DIR}/ca/root-ca-key.pem \
  -CAcreateserial \
  -out ${BASE_DIR}/admin/admin.pem \
  -days ${DAYS} -sha256

rm -f ${BASE_DIR}/admin/admin.csr

echo "[3/6] Create Node certificates (DNS-only SAN)..."
for NODE in "${NODES[@]}"; do
  echo "  → ${NODE}"

  cat > ${BASE_DIR}/nodes/${NODE}-ext.cnf <<EOF
subjectAltName = @alt_names
extendedKeyUsage = serverAuth, clientAuth

[alt_names]
DNS.1 = ${NODE}
DNS.2 = ${NODE}.blackhole.local
EOF

  openssl genrsa -out ${BASE_DIR}/nodes/${NODE}-key.pem 4096

  openssl req -new \
    -key ${BASE_DIR}/nodes/${NODE}-key.pem \
    -out ${BASE_DIR}/nodes/${NODE}.csr \
    -subj "/C=VN/O=BlackHole/OU=Infrastructure/CN=${NODE}"

  openssl x509 -req \
    -in ${BASE_DIR}/nodes/${NODE}.csr \
    -CA ${BASE_DIR}/ca/root-ca.pem \
    -CAkey ${BASE_DIR}/ca/root-ca-key.pem \
    -CAcreateserial \
    -out ${BASE_DIR}/nodes/${NODE}.pem \
    -days ${DAYS} -sha256 \
    -extfile ${BASE_DIR}/nodes/${NODE}-ext.cnf

  rm -f ${BASE_DIR}/nodes/${NODE}.csr ${BASE_DIR}/nodes/${NODE}-ext.cnf
done

echo "[6/6] DONE – Certificates ready at: ${BASE_DIR}"
Script sẽ sinh ra các cert như kết quả bên dưới: 
gcsc@gcsc:/opt/blackhole/config$ bash gen.sh
[1/6] Create Root CA...
[2/6] Create Admin certificate...
Certificate request self-signature ok
subject=C = VN, O = BlackHole, OU = Security, CN = admin
[3/6] Create Node certificates (DNS-only SAN)...
  → blackhole-aio
Certificate request self-signature ok
subject=C = VN, O = BlackHole, OU = Infrastructure, CN = blackhole-aio
[6/6] DONE – Certificates ready at: /opt/blackhole/config/certs
gcsc@gcsc:/opt/blackhole/config$ ls -la certs/nodes/
total 16
drwxrwxr-x 2 gcsc gcsc 4096 Jan 21 06:57 .
drwxrwxr-x 5 gcsc gcsc 4096 Jan 21 06:57 ..
-rw------- 1 gcsc gcsc 3268 Jan 21 06:57 blackhole-aio-key.pem
-rw-rw-r-- 1 gcsc gcsc 2065 Jan 21 06:57 blackhole-aio.pem
gcsc@gcsc:/opt/blackhole/config$ ls -la certs/ca/
total 20
drwxrwxr-x 2 gcsc gcsc 4096 Jan 21 06:57 .
drwxrwxr-x 5 gcsc gcsc 4096 Jan 21 06:57 ..
-rw------- 1 gcsc gcsc 3272 Jan 21 06:57 root-ca-key.pem
-rw-rw-r-- 1 gcsc gcsc 1956 Jan 21 06:57 root-ca.pem
-rw-rw-r-- 1 gcsc gcsc   41 Jan 21 06:57 root-ca.srl
gcsc@gcsc:/opt/blackhole/config$ ls -la certs/admin
total 16
drwxrwxr-x 2 gcsc gcsc 4096 Jan 21 06:57 .
drwxrwxr-x 5 gcsc gcsc 4096 Jan 21 06:57 ..
-rw------- 1 gcsc gcsc 3272 Jan 21 06:57 admin-key.pem
-rw-rw-r-- 1 gcsc gcsc 1826 Jan 21 06:57 admin.pem
Phân lại quyền để đảm bảo bảo mật 
chmod 600 certs/ca/*
chmod 600 certs/admin/*
chmod 600 certs/nodes/*

​
Bước 4: Cài đặt BlackHole Core

  1. Khởi tạo các biến môi trường Cài đặt biến môi trường trỏ tới JDK 
    sudo cat >> /etc/environment <<EOF
BLACKHOLE_JAVA_HOME=/opt/blackhole/jdk
EOF
source /etc/environment
    Đặt mật khẩu admin khởi tạo 
    export BLACKHOLE_INITIAL_ADMIN_PASSWORD=<custom-admin-password>
  2. Cấu hình file blackhole.yml như sau BlackHole Core: 
    cat >> /opt/blackhole/config/blackhole.yml << EOF
node.name: blackhole-aio
discovery.type: single-node
bootstrap.memory_lock: false

network.host: 0.0.0.0
plugins.security.disabled: false
plugins.security.ssl.transport.pemcert_filepath: certs/nodes/blackhole-aio.pem
plugins.security.ssl.transport.pemkey_filepath: certs/nodes/blackhole-aio-key.pem
plugins.security.ssl.transport.pemtrustedcas_filepath: certs/ca/root-ca.pem
plugins.security.ssl.transport.enforce_hostname_verification: false

plugins.security.ssl.http.enabled: true
plugins.security.ssl.http.pemcert_filepath: certs/nodes/blackhole-aio.pem
plugins.security.ssl.http.pemkey_filepath: certs/nodes/blackhole-aio-key.pem
plugins.security.ssl.http.pemtrustedcas_filepath: certs/ca/root-ca.pem

plugins.security.allow_default_init_securityindex: true
plugins.security.authcz.admin_dn:
  - "CN=admin,OU=Security,O=BlackHole,C=VN"

plugins.security.audit.type: internal_blackhole

plugins.security.enable_snapshot_restore_privilege: true
plugins.security.check_snapshot_restore_write_privileges: true
plugins.security.restapi.roles_enabled: [all_access, security_rest_api_access]
plugins.security.system_indices.enabled: true
EOF
  3. Khởi chạy BlackHole Core 
    /opt/blackhole/bin/blackhole
  4. Trên một node kiểm tra trạng thái 
    curl -XGET https://localhost:9200/_cat/nodes?v -u 'admin' --insecure

​
Bước 4 (Optional): Cài đặt BlackHole dưới dạng Service

  1. Tạo user blackhole
sudo adduser --system  --shell /bin/bash --no-create-home  blackhole
  1. Thêm user hiện tại vào group blackhole
sudo usermod -g blackhole blackhole
sudo usermod -aG blackhole $USER
  1. Gán quyền sở hữu thư mục cho user
sudo chown -R blackhole:blackhole /opt/blackhole
  1. Tạo file systemd service trên tất cả các node
sudo cat >> /etc/systemd/system/blackhole.service << EOF
[Unit]
Description=BlackHole Search Engine
Wants=network-online.target
After=network-online.target

[Service]
Type=forking
RuntimeDirectory=blackhole

WorkingDirectory=/opt/blackhole
ExecStart=/opt/blackhole/bin/blackhole -d

User=blackhole
Group=blackhole

StandardOutput=journal
StandardError=inherit

LimitNOFILE=65535
LimitNPROC=4096
LimitAS=infinity
LimitFSIZE=infinity

TimeoutStopSec=0
KillSignal=SIGTERM
KillMode=process
SendSIGKILL=no
SuccessExitStatus=143
TimeoutStartSec=75

[Install]
WantedBy=multi-user.target
EOF
  1. Khởi chạy BlackHole
sudo systemctl daemon-reload
sudo systemctl enable blackhole.service
  1. Kiểm tra trạng thái
sudo systemctl status blackhole
  1. Kiểm tra log
journalctl -u blackhole -f