Cấu hình và dòng lệnh
Vị trí tệp
| Nội dung | Linux | Windows |
|---|---|---|
| Cấu hình cục bộ | /etc/accesshub-agent/agent.yaml | C:\ProgramData\AccessHubAgent\agent.yaml |
| Thông tin đăng nhập | /var/lib/accesshub-agent/credentials.json (0600) | C:\ProgramData\AccessHubAgent\credentials.bin (DPAPI, ACL chỉ SYSTEM và Administrators) |
| Cấu hình từ xa gần nhất | /var/lib/accesshub-agent/remote-config.json | C:\ProgramData\AccessHubAgent\remote-config.json |
| WAL | /var/lib/accesshub-agent/wal/ | C:\ProgramData\AccessHubAgent\wal\ |
| Log | journald, hoặc /var/log/accesshub-agent/agent.log nếu bật | Event Log và C:\ProgramData\AccessHubAgent\logs\agent.log |
| Tệp License dùng một lần | /etc/accesshub-agent/license.token (0600) | C:\ProgramData\AccessHubAgent\license.token |
Thứ tự ưu tiên khi trùng khóa: tham số dòng lệnh, biến môi trường AH_*, cấu hình cục bộ, cấu hình từ xa (chỉ các khóa cho phép), mặc định.
Tệp cấu hình mẫu
# /etc/accesshub-agent/agent.yaml
collector_url: https://collector.example.com # bắt buộc, chỉ https
ca_file: "" # ghim CA tùy chọn
insecure_skip_verify: false # chỉ dev, agent in cảnh báo mỗi giờ nếu bật
proxy_url: "" # http(s) proxy tùy chọn, mặc định theo biến môi trường hệ thống
state_dir: /var/lib/accesshub-agent # thư mục trạng thái (thông tin đăng nhập, WAL), Windows: C:\ProgramData\AccessHubAgent
interval: 30s # 10s đến 300s, mặc định 30s
send_timeout: 15s
collect_timeout: 5s
allow_remote_config: true # false: bỏ qua mọi cấu hình từ xa
buffer:
max_bytes: 52428800 # 50 MiB
max_age: 24h
catch_up_batches: 2 # 1 đến 10: số lô bù gửi thêm sau mỗi lô trực tiếp
limits:
max_series: 500
memory_limit: 64MiB # GOMEMLIMIT
log:
level: info # debug, info, warn, error
format: text # text, json
file: "" # rỗng: journald hoặc Event Log
metrics:
cpu: { enabled: true, include_iowait_in_usage: false }
memory: { enabled: true }
disk:
enabled: true
include_fstypes: [] # rỗng: dùng mặc định
exclude_fstypes: []
exclude_mounts: []
include_network_fs: false
net:
enabled: true
include: [] # regex
exclude: []
uptime: { enabled: true }
pressure: { enabled: true } # PSI của kernel Linux, bỏ qua lặng lẽ nếu không có
# Chọn chỉ số theo tên hoặc glob (xem docs/03-metrics-catalog.md):
include: [] # rỗng: mọi chỉ số bật mặc định. Có giá trị: chỉ những chỉ số khớp
exclude: [] # loại chỉ số, thắng include. Ví dụ: ["mem_slab_bytes", "psi_*", "net_*_packets_per_sec"]
inventory: # kiểm kê phần cứng và hệ điều hành (AGT-9)
enabled: true
interval: 6h # 1h đến 24h: gửi lại tối thiểu theo chu kỳ này dù không đổi
credentials:
renew_after: 720h # 48h đến 2160h: xin token mới khi token đủ tuổi này (AGT-10)
checks: [] # thường lấy từ cấu hình từ xa
# ví dụ check cục bộ:
# checks:
# - { id: nginx, type: service, name: nginx }
# - { id: web80, type: port, port: 80, proto: tcp }
# - { id: site, type: http, url: "https://app.example.com/health", expect_status: 200, timeout: 5s }
# - { id: cert, type: cert, target: "app.example.com:443" }
labels: {} # nhãn tĩnh tùy chọn, phải nằm trong danh sách trắng của collectorKiểm tra hợp lệ nghiêm ngặt: khóa lạ là lỗi (tránh gõ sai lặng lẽ), khóa trùng là lỗi, giá trị ngoài khoảng bị từ chối, check-config in lỗi dạng tệp:dòng: khóa: nội dung và thoát mã 3. Lỗi cú pháp và khóa lạ được báo trước, lỗi khoảng giá trị chỉ báo khi phần trước đã sạch. Thời lượng viết dạng 30s, 5m, 24h. Dung lượng viết 64MiB, 50MB hoặc số byte. Tệp mặc định vắng mặt không phải lỗi (chạy bằng mặc định và biến môi trường), tệp chỉ định rõ bằng --config hoặc AH_CONFIG mà vắng mặt là lỗi.
Biến môi trường
| Biến | Ý nghĩa |
|---|---|
AH_COLLECTOR_URL | Ghi đè collector_url |
AH_LICENSE | License cho lần enroll đầu |
AH_LICENSE_FILE | Đường dẫn tệp chứa License |
AH_CONFIG | Đường dẫn tệp cấu hình khác |
AH_STATE_DIR | Thư mục trạng thái khác (state_dir) |
AH_LOG_LEVEL | Ghi đè cấp log |
AH_INSECURE_SKIP_VERIFY | Chỉ dev |
Các lệnh đọc cấu hình (run, check-config, collect-once, inventory, enroll) đều nhận --config, --collector, --state-dir, --log-level, ghi đè biến môi trường và tệp.
Token không bao giờ được in ra log, status hay diag. Khi cần hiển thị chỉ hiện 4 ký tự đầu và cuối đã che.
Dòng lệnh
accesshub-agent <lệnh> [tùy chọn]| Lệnh | Mô tả |
|---|---|
run | Chạy ở foreground (dùng bởi service manager, hoặc gỡ lỗi). Cờ --windows-service do service install đặt, chỉ dùng khi SCM khởi động: nhận Stop và Shutdown, báo mã thoát cho SCM, ghi log vào <state_dir>\logs\agent.log nếu log.file trống |
enroll | Đăng ký agent với collector. Nhận token qua --token-file, --token-stdin hoặc biến môi trường. Cờ --token có nhưng cảnh báo về argv. --force để enroll lại |
status | Đọc status.json mà agent đang chạy ghi lại mỗi chu kỳ (agent không mở cổng): phiên bản, PID, trạng thái gửi, lần gửi cuối, lỗi cuối, WAL, độ lệch đồng hồ, cấu hình trung tâm (etag, khóa đã áp, cảnh báo), số báo cáo kiểm kê. -json in nguyên bản. Mã thoát 0 khi tệp mới (cập nhật trong 3 chu kỳ, tối thiểu 2 phút) và gửi ok, 1 khi không, 4 khi chưa enroll |
version | Phiên bản, commit, proto, hệ điều hành, kiến trúc |
check-config | Kiểm tra tệp cấu hình, không cần kết nối |
diag | Ghi gói chẩn đoán .tar.gz (0600, -o chọn đường dẫn, mặc định accesshub-agent-diag-<host>-<thời điểm>.tar.gz): version.txt, config-local.yaml (URL đã che mật khẩu), identity.json (agent_id, thời điểm enroll, không có token), status.json, remote-config.json, wal.json (số tệp, dung lượng), inventory.json, ping.json (thời gian phản hồi, độ lệch đồng hồ; -offline bỏ qua). Trước khi ghi, mọi tệp được quét mẫu ahat_, ahet_, Bearer và chính token đang dùng; thấy là từ chối ghi. Log nằm ở journald (journalctl -u accesshub-agent), không đóng gói |
service install | Cài dịch vụ: Linux tạo user, thư mục, ghi agent.yaml mẫu nếu chưa có (0640, --collector URL điền collector_url) và unit systemd (cần root, --binary, --enable, không tự khởi động). Windows (ADR 0008, cần dấu nhắc quản trị): khóa ACL C:\ProgramData\AccessHubAgent chỉ còn SYSTEM, Administrators và NT SERVICE\AccessHubAgent, ghi agent.yaml mẫu nếu chưa có, đăng ký dịch vụ AccessHubAgent (tài khoản ảo, khôi phục 5 s, 30 s, 60 s, khởi động thủ công, --enable để tự động trễ, không tự khởi động) |
service uninstall | Gỡ dịch vụ |
service start, service stop, service restart | Điều khiển dịch vụ |
uninstall | Gỡ hoàn toàn (dịch vụ, tùy chọn --purge xóa dữ liệu và thông tin đăng nhập; Windows giữ nguyên dữ liệu nếu không có --purge). Không báo collector (quản trị viên thu hồi trong Access Hub) |
metrics list | Liệt kê danh mục chỉ số kèm trạng thái hiệu lực theo cấu hình đang nạp (enabled, disabled, planned, unsupported). Tùy chọn --group cpu|memory|disk|net|system|checks|agent, --format table|json, --lang vi|en. Không cần collector_url |
metrics show <tên> | Chi tiết một chỉ số: nhóm, đơn vị, nhãn, nền tảng, mặc định, bắt buộc, mô tả vi và en, trạng thái hiệu lực. Tên không có trong danh mục thì thoát với mã 1 |
inventory | Thu và in báo cáo kiểm kê dạng JSON (đúng nội dung gửi lên collector), không gửi và không cần collector_url. Dùng để so với lscpu, free -b, df -B1, ip -br addr |
collect-once | Thu thập hai lần cách nhau --gap (mặc định 1s, để có chỉ số tốc độ), in mẫu thứ hai dạng JSON, không gửi và không cần collector_url. Dùng thử nghiệm và hỗ trợ |
Mã thoát: 0 thành công, 1 lỗi chung, 2 sai cú pháp, 3 cấu hình không hợp lệ, 4 chưa enroll, 5 enroll bị từ chối, 6 không kết nối được.
Ví dụ enroll
Linux, không để token vào lịch sử shell. Enroll phải chạy dưới tài khoản dịch vụ accesshub-agent (do gói tạo) để credentials.json (0600) đọc được bởi dịch vụ, token đi qua stdin.
Windows (PowerShell, quản trị). service install phải chạy trước enroll để thư mục dữ liệu đã được khóa ACL, nếu không credentials.json thừa hưởng quyền của ProgramData.
read -rs TOKEN
printf '%s\n' "$TOKEN" | sudo -u accesshub-agent accesshub-agent enroll --collector https://collector.example.com --token-stdin
unset TOKEN
sudo systemctl enable --now accesshub-agent$exe = "C:\Program Files\AccessHubAgent\accesshub-agent.exe"
& $exe service install --collector https://collector.example.com
$env:AH_LICENSE = "<token>"
& $exe enroll
Remove-Item Env:AH_LICENSE
& $exe service startLinux: cài từ gói thì postinstall làm các bước này khi có ACCESSHUB_COLLECTOR_URL và token (xem 06-packaging-install.md). Nếu không dùng gói: sudo accesshub-agent service install tạo tài khoản, thư mục và unit.
Sau khi enroll thành công, tệp License (nếu có) bị xóa an toàn.
Thứ tự ưu tiên nguồn token: cờ (--token-file, --token-stdin, --token), rồi AH_LICENSE_FILE, rồi AH_LICENSE, rồi tệp mặc định. Hai cờ nguồn cùng lúc là lỗi cú pháp (mã 2). --token in cảnh báo vì giá trị lộ trong argv. Token không bao giờ vào log.
Hành vi cần biết:
- Đã có
credentials.jsonthìenrolltừ chối (mã 1) trừ khi có--force. - Tệp token chỉ bị xóa sau khi đã lưu thông tin xác thực thành công. Enroll lỗi thì giữ nguyên tệp để thử lại.
- Collector trả 400, 401, 403, 409, 422 hoặc 426 cho enroll thì mã thoát 5. Lỗi mạng hoặc 5xx thì mã 6. 422
quota_exceedednghĩa là gói của công ty đã đủ số agent: thu hồi agent không dùng hoặc nâng gói trong Access Hub rồi chạy lại. runkhi chưa enroll in hướng dẫn và thoát mã 4.collector_urltrong cấu hình cục bộ luôn thắng URL collector trả về lúc enroll (URL đó chỉ được lưu trongcredentials.json).
Cấu hình từ xa
Collector trả cấu hình qua GET /agent/v1/config (ETag). Lược đồ do Collector định nghĩa (xem AgentConfig ở 10-wire-contract.md). Agent chỉ nhận các khóa sau, mọi khóa khác bị bỏ qua và ghi log:
| Khóa | Giới hạn |
|---|---|
interval | 10s đến 300s |
checks[] | Tối đa 50 mục, loại service, port, tcp, http, cert, không có lệnh tùy ý |
metrics.*.enabled | Bật, tắt bộ thu |
metrics.include, metrics.exclude | Tên hoặc glob trong danh mục chỉ số. Ở cấu hình cục bộ mẫu không khớp là lỗi cấu hình, ở cấu hình từ xa thì mẫu đó bị bỏ qua và ghi log. Chỉ số bắt buộc (nhóm agent) không bao giờ bị loại |
disk.exclude_mounts, net.exclude | Danh sách regex đã kiểm tra độ phức tạp |
limits.max_series | Không vượt giới hạn cứng của agent |
collector_url | Chỉ GĐ 3, phải là https, kèm chữ ký hoặc cần xác nhận cục bộ (xem ADR agent 0003) |
Bất biến bảo mật:
- Cấu hình từ xa không bao giờ chứa đường dẫn thực thi, lệnh, script, hay đường dẫn tệp tùy ý (ADR 0005).
- Cấu hình cục bộ luôn thắng khi có xung đột về khóa an toàn (
allow_remote_config,ca_file,insecure_skip_verify,log.file). - Kiểm tra
httpvàtcpdo quản trị viên Access Hub khai báo có thể tới địa chỉ nội bộ. Agent chặn mặc định các đích link-local (169.254.0.0/16, gồm metadata đám mây) trừ khichecks_allow_link_local: truecục bộ, để tránh dùng agent làm bàn đạp SSRF. - Regex bị giới hạn độ dài (200 ký tự) và dùng engine RE2 của Go (không backtracking).
Cấu hình từ xa hợp lệ gần nhất được lưu trên đĩa (remote-config.pb, 0600) để agent khởi động lại khi collector chưa liên lạc được.
Hiện thực (AGT-10, internal/remotecfg): agent kéo GET /config mỗi 300 giây (cộng trừ 20%, pha lệch theo agent_id) và khi config_etag trong phản hồi metrics đổi (tối đa 1 lần mỗi 30 giây). Trường bằng 0, rỗng hoặc vắng nghĩa là trung tâm không quản lý trường đó, agent giữ giá trị cục bộ. Có collectors thì thay cờ bật tắt cpu, memory, disk, net, uptime (pressure không có cờ trung tâm, giữ cục bộ), danh sách lọc chỉ thay khi khác rỗng. limits.max_series chỉ hạ, không nâng. Giá trị sai bị bỏ từng khóa kèm cảnh báo, kết quả vẫn sai thì bỏ cả bản. Kiểm tra (checks) từ trung tâm được thêm sau check cục bộ (check cục bộ thắng khi trùng id, tổng tối đa 50, check sai bị bỏ từng mục kèm cảnh báo). Đổi bộ thu thì agent dựng lại bộ thu ở chu kỳ kế tiếp (cũng áp dụng cho SIGHUP). Cấu hình hiệu lực = cục bộ cộng trung tâm, xem bằng status.
Kiểm tra (checks, AGT-8)
| Loại | Khóa | Chỉ số | Cách đo |
|---|---|---|---|
service | name (unit systemd, thêm .service nếu thiếu đuôi) | service_up{name} | Đọc cgroup.events (populated 1) của unit trong /sys/fs/cgroup (cgroup v1: cgroup.procs). Không chạy lệnh, không cần quyền. Chỉ Linux |
port | port, proto (tcp, udp) | port_up{port,proto} | Có socket TCP ở trạng thái LISTEN, hoặc socket UDP bất kỳ, gắn vào cổng (/proc/net/tcp*, udp*). Chỉ Linux |
tcp | target (host:port) | tcp_connect_up, tcp_connect_seconds{target} | Kết nối TCP |
http | url, expect_status (mặc định 200) | http_up, http_duration_seconds, http_status_code{target} | GET, tối đa 3 chuyển hướng, đọc tối đa 64 KiB thân. Nhãn target là URL đã bỏ thông tin đăng nhập, query, fragment |
cert | target (host:port) | cert_days_left{target} | Bắt tay TLS với SNI, đọc ngày hết hạn của chứng chỉ lá kể cả khi chứng chỉ sai hoặc đã hết hạn (không tin cậy, chỉ đọc) |
timeout mỗi check 1 đến 15 giây (mặc định 5). Các check chạy nền, song song tối đa 8, mỗi chu kỳ gửi kết quả của lần chạy xong gần nhất, nên check chậm không làm trễ số liệu khác. Mọi kết nối tới địa chỉ link-local (169.254.0.0/16, fe80::/10) bị chặn ở bước quay số (cả khi tên miền trỏ tới đó) trừ khi checks_allow_link_local: true cục bộ.
Đồng hồ
Mỗi phản hồi metrics mang giờ collector, agent đo độ lệch (agent_clock_skew_seconds, dương khi đồng hồ agent chậm). Lệch từ 5 giây: ghi cảnh báo một lần (kiểm tra NTP). Lệch từ 60 giây: agent dời mốc thời gian mẫu theo giờ collector để mẫu không rơi khỏi cửa sổ nhận của collector (24 giờ về trước, 5 phút về sau); sent_at_ms giữ giờ máy để gỡ lỗi.
Tín hiệu
| Tín hiệu (Linux) | Hành vi |
|---|---|
SIGTERM, SIGINT | Dừng êm |
SIGHUP | Nạp lại cấu hình cục bộ |
SIGUSR1 | In trạng thái vào log |
Cấu hình nạp lại sai thì agent giữ cấu hình đang chạy và ghi lỗi vào log. Log ghi ra stderr (journald thu giữ). Khi đặt log.file, tệp xoay vòng ở 10 MB và giữ một bản cũ (agent.log.1), tổng tối đa 20 MB. Mọi thông điệp và thuộc tính log đi qua bộ lọc che ahat_*, ahet_*, Bearer ... và khóa tên chứa token, authorization, password, secret.
Windows dùng Service Control Manager: đã nhận Stop và Shutdown (dừng êm, tối đa 30 giây). Nạp lại cấu hình (ParamChange) chưa làm, dùng service restart.