Đóng gói, cài đặt hàng loạt, cập nhật

12 phút đọcCập nhật 02/10/2026access-hub-agent, docs/06-packaging-install.md

Trước khi bắt đầu

Một License cấp trong Access Hub (Giám sát, License)

Địa chỉ collector bắt đầu bằng https://

Quyền root hoặc sudo trên máy cần giám sát

Máy được đi ra collector qua 443/TCP (và DNS 53) theo 09-operations.md

Linux có systemd: Ubuntu 18.04+, Debian 10+, RHEL, CentOS, Rocky, Alma 7+, Amazon Linux 2+

Windows 10 1809+, 11, Server 2016+: chỉ cài thủ công, MSI chưa xây

Áp dụng choLinux (deb, rpm, tar.gz) Sẵn sàngWindows (cài thủ công) Đang làmWindows (MSI) Chưa có

Sản phẩm phát hành

Tệp	Nền tảng	Ghi chú
accesshub-agent_<ver>_amd64.deb, _arm64.deb	Debian, Ubuntu	Dựng bằng nfpm
accesshub-agent-<ver>-1.x86_64.rpm, -1.aarch64.rpm	RHEL, CentOS, Rocky, Alma, Amazon Linux	Dựng bằng nfpm
accesshub-agent-<ver>-linux-<arch>.tar.gz	Linux khác	Binary tĩnh, unit, cấu hình mẫu, README
AccessHubAgent-<ver>-x64.msi, -arm64.msi	Windows	WiX, ký Authenticode
install.sh	Linux	Tải, xác minh checksum, cài
install.ps1	Windows	Tải MSI, xác minh, cài im lặng
SHA256SUMS, SHA256SUMS.sig	Tất cả	Ký cosign hoặc GPG
sbom.cdx.json	Tất cả	Danh mục phụ thuộc

Phiên bản dạng 1.2.3-rc.1 trong tên gói deb và rpm được nfpm đổi thành 1.2.3~rc.1 để sắp xếp trước bản chính thức. Bản dựng không có tag dùng 0.0.0-dev.<sha>.

Đặt tên và nơi lưu trữ: xem Q2 (kho gói, ví dụ tự dựng apt và yum repo hoặc dùng dịch vụ như packagecloud, Artifactory, GitHub Releases).

Nội dung gói Linux

Đường dẫn	Nội dung
/usr/bin/accesshub-agent	Binary
/lib/systemd/system/accesshub-agent.service	Unit đã hardening
/etc/accesshub-agent/agent.yaml	Cấu hình mẫu 0640 root:accesshub-agent (có thể chứa mật khẩu proxy), đánh dấu config (không ghi đè khi nâng cấp)
/var/lib/accesshub-agent/	Trạng thái, 0750, chủ accesshub-agent
/usr/share/doc/accesshub-agent/	README, giấy phép, changelog

Đường dẫn unit: /lib/systemd/system/ trong deb, /usr/lib/systemd/system/ trong rpm. Nội dung unit là một tệp duy nhất internal/svc/accesshub-agent.service, được nhúng vào binary (cho service install) và đóng vào gói.

Script gói (thư mục packaging/scripts/). deb truyền configure, upgrade, remove, purge, deconfigure. rpm truyền số: postinst nhận 1 (cài mới) hoặc 2 (nâng cấp), prerm và postrm nhận 0 (gỡ) hoặc 1 (nâng cấp). Script xử lý cả hai kiểu.

• preinstall.sh: tạo user và group hệ thống accesshub-agent (useradd, hoặc adduser nếu không có), shell nologin, không có thư mục home. Chạy lại an toàn.
• postinstall.sh: tạo /var/lib/accesshub-agent và /var/log/accesshub-agent (0750, chủ accesshub-agent), systemctl daemon-reload, try-restart (chỉ khởi động lại dịch vụ đang chạy để nâng cấp nhận binary mới). Không bao giờ khởi động dịch vụ khi chưa enroll. Chỉ khi có biến môi trường mới enroll (bảng dưới).
• preremove.sh: disable --now chỉ khi gỡ thật (remove, deconfigure, rpm 0). Nâng cấp không dừng dịch vụ.
• postremove.sh: daemon-reload. Chỉ với deb purge mới xóa /var/lib, /var/log, /etc/accesshub-agent và user. Gỡ thường và nâng cấp giữ thông tin đăng nhập. rpm không có purge: chạy sudo accesshub-agent uninstall --purge trước khi dnf remove nếu muốn xóa sạch.

Biến môi trường cho postinstall.sh (và cho install.sh, chuyển tiếp nguyên vẹn):

Biến	Ý nghĩa
ACCESSHUB_COLLECTOR_URL	Địa chỉ collector, phải bắt đầu bằng https:// và chỉ chứa ký tự URL an toàn. Được ghi vào collector_url trong agent.yaml
ACCESSHUB_LICENSE	License
ACCESSHUB_LICENSE_FILE	Tệp chứa token, bị xóa an toàn (shred) sau khi enroll thành công, giữ nguyên nếu enroll lỗi
ACCESSHUB_PROXY_URL	Ghi vào proxy_url
ACCESSHUB_NO_START	1: enroll và enable nhưng không khởi động (dùng cho image mẫu)

Cần cả URL và token (hoặc tệp token) thì mới enroll, thiếu một thì bỏ qua và in cảnh báo. Enroll chạy dưới tài khoản accesshub-agent (runuser, dự phòng su) để credentials.json do đúng tài khoản dịch vụ sở hữu, token đi qua pipe vào enroll --token-stdin, không bao giờ nằm trong argv. Đã có credentials.json thì giữ nguyên, không enroll lại. Enroll lỗi không làm gói cài lỗi: script in lệnh sửa (sudo -u accesshub-agent /usr/bin/accesshub-agent enroll --token-file <tệp>) rồi thoát 0, dịch vụ chưa được bật.

Lưu ý: postinstall.sh sửa agent.yaml (tệp config đánh dấu noreplace) khi có ACCESSHUB_COLLECTOR_URL. Nếu gói sau này đổi nội dung agent.yaml mẫu, dpkg có thể hỏi giữ hay thay tệp: chọn giữ.

Dùng thủ công không qua gói (tar.gz hoặc binary chép tay):

sudo ./accesshub-agent service install --binary /usr/local/bin/accesshub-agent   # tạo user, thư mục, ghi unit, daemon-reload
sudo -u accesshub-agent /usr/local/bin/accesshub-agent enroll --collector https://collector.example.com --token-file /path/token
sudo accesshub-agent service start                                               # hoặc: service install --enable

service install cần root, ghi unit (ExecStart trỏ tới --binary, mặc định là binary đang chạy) và agent.yaml mẫu (0640 root:accesshub-agent) nếu chưa có tệp, không bao giờ khởi động. --collector URL (https) điền collector_url vào tệp mới, tệp đã có không bị sửa. Nhớ đặt collector_url rồi enroll trước khi start, nếu không dịch vụ dừng ở failed (mã 3). service uninstall dừng, tắt và xóa unit, giữ dữ liệu. uninstall --purge xóa thêm dữ liệu, log, cấu hình và user. service start|stop|restart gọi systemctl. Trên hệ điều hành khác Linux các lệnh này báo chưa hỗ trợ (dịch vụ Windows là AGT-7).

Ràng buộc: gói không phụ thuộc thư viện nào ngoài systemd. Không dùng curl | sh ẩn.

Unit systemd

Chạy dưới accesshub-agent, không quyền đặc biệt: NoNewPrivileges, ProtectSystem=strict (chỉ ghi được /var/lib/accesshub-agent và /var/log/accesshub-agent), ProtectHome, PrivateTmp, PrivateDevices, ProtectKernel*, ProtectControlGroups, MemoryDenyWriteExecute, RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX, SystemCallFilter=@system-service, CapabilityBoundingSet= rỗng, UMask=0077, MemoryMax=96M, CPUQuota=25%, TasksMax=128, LimitNOFILE=1024. Directive mới hơn systemd của máy (ví dụ Rocky 8, systemd 239) bị bỏ qua kèm cảnh báo, không làm unit lỗi.

Restart=on-failure, RestartSec=5, và RestartPreventExitStatus=2 3 4 5 (cú pháp, cấu hình sai, chưa enroll, enroll bị từ chối: thử lại vô ích), giới hạn 10 lần khởi động trong 300 giây. ExecReload gửi SIGHUP.

Cài đặt Linux

Nhanh (từng máy)

curl -fsSL https://downloads.example.com/agent/install.sh -o install.sh
sha256sum install.sh        # đối chiếu với giá trị công bố
sudo ACCESSHUB_COLLECTOR_URL=https://collector.example.com \
     ACCESSHUB_LICENSE=ahet_xxx bash install.sh

install.sh (nguồn: packaging/install.sh, được make package chép vào bộ phát hành) tự nhận diện dpkg hoặc rpm và kiến trúc, tải SHA256SUMS, xác minh chữ ký của nó, lấy tên gói từ chính danh sách đã xác minh, kiểm tra sha256 của gói rồi cài bằng apt-get, dnf, yum hoặc dpkg/rpm. Việc enroll và khởi động do postinstall.sh của gói làm (cùng các biến ACCESSHUB_*).

Token chỉ nhận qua ACCESSHUB_LICENSE hoặc ACCESSHUB_LICENSE_FILE, cờ --token bị từ chối vì lộ trong danh sách tiến trình. Tải chỉ qua https:// (hoặc file:// cho mirror nội bộ).

Tùy chọn: --version V (mặc định đọc <base>/latest), --base-url URL (hoặc ACCESSHUB_DOWNLOAD_BASE), --pubkey FILE (hoặc ACCESSHUB_PUBKEY_FILE), --allow-unsigned, --proxy URL, --no-start, --dry-run (tải và xác minh, in lệnh sẽ chạy, không cài, không cần root).

Xác minh chữ ký: khóa PGP (gpg --verify, cần gpg) hoặc khóa PEM (cosign verify-blob, cần cosign), chọn theo nội dung tệp khóa. Đóng theo mặc định: không có --pubkey thì script dừng, trừ khi có --allow-unsigned (chỉ để thử nghiệm, vẫn bắt buộc khớp checksum và in cảnh báo). Khóa ký phát hành chưa tồn tại (Q2, Q3 chờ quyết định) nên hiện chỉ dùng được --allow-unsigned với bản dựng nội bộ.

Kho gói (khuyến nghị cho số lượng lớn)

Debian, Ubuntu

# Debian, Ubuntu
curl -fsSL https://pkg.example.com/accesshub.gpg | sudo gpg --dearmor -o /usr/share/keyrings/accesshub.gpg
echo "deb [signed-by=/usr/share/keyrings/accesshub.gpg] https://pkg.example.com/apt stable main" | sudo tee /etc/apt/sources.list.d/accesshub.list
sudo apt update && sudo apt install accesshub-agent

RHEL, CentOS, Rocky, Alma

# RHEL, CentOS, Rocky, Alma
sudo rpm --import https://pkg.example.com/accesshub.gpg
sudo tee /etc/yum.repos.d/accesshub.repo <<'EOF'
[accesshub]
name=Access Hub Agent
baseurl=https://pkg.example.com/rpm/$basearch
gpgcheck=1
gpgkey=https://pkg.example.com/accesshub.gpg
EOF
sudo dnf install accesshub-agent

Nâng cấp qua kho: apt upgrade, dnf upgrade, cấu hình được giữ.

Cài đặt Windows

Cài thủ công không MSI (ĐÃ XÂY, AGT-7, ADR 0008)

Dùng khi chưa có MSI hoặc cho máy thử nghiệm. Chạy PowerShell với quyền quản trị, bước service install phải đi trước enroll:

$exe = "C:\Program Files\AccessHubAgent\accesshub-agent.exe"
& $exe service install --collector https://collector.example.com
$env:AH_LICENSE = "<license>"; & $exe enroll; Remove-Item Env:AH_LICENSE
& $exe service start
icacls "C:\ProgramData\AccessHubAgent"   # chỉ còn SYSTEM, Administrators, NT SERVICE\AccessHubAgent

Dịch vụ AccessHubAgent chạy bằng tài khoản ảo NT SERVICE\AccessHubAgent, log ở C:\ProgramData\AccessHubAgent\logs\agent.log. Gỡ: service uninstall (giữ dữ liệu) hoặc uninstall --purge. Chưa chạy thử trên Windows thật.

Phần MSI bên dưới là THIẾT KẾ, CHƯA XÂY. MSI sẽ chỉ chép tệp rồi gọi các lệnh trên, không lặp lại logic ACL.

MSI tương tác

Trình cài đặt hỏi COLLECTOR_URL và LICENSE.

Im lặng, hàng loạt

msiexec /i AccessHubAgent-1.0.0-x64.msi /qn /l*v C:\Windows\Temp\ahagent.log `
  COLLECTOR_URL=https://collector.example.com LICENSE=ahet_xxx

Thuộc tính MSI:

Thuộc tính	Ý nghĩa
COLLECTOR_URL	Địa chỉ collector (bắt buộc cho enroll tự động)
LICENSE	License (được ghi tạm vào tệp bảo vệ ACL rồi xóa sau enroll, không nằm trong registry)
INSTALLDIR	Mặc định C:\Program Files\AccessHubAgent
PROXY_URL	Proxy tùy chọn
START_SERVICE	1 (mặc định) hoặc 0
CA_FILE	Tệp CA tùy chọn

Lưu ý: tham số dòng lệnh MSI có thể nằm trong log cài đặt và lịch sử tiến trình. Khuyến nghị dùng License có hạn ngắn, dùng một lần, ghi log MSI vào thư mục hạn chế, hoặc dùng LICENSE_FILE để trỏ tới tệp do công cụ triển khai đặt sẵn.

Nâng cấp: MSI có UpgradeCode cố định và MajorUpgrade, giữ cấu hình và thông tin đăng nhập. Gỡ: msiexec /x hoặc Apps and Features, tùy chọn PURGE=1 xóa dữ liệu.

Dựng bộ phát hành

go install github.com/goreleaser/nfpm/v2/cmd/[email protected]   # một lần
make package                                                # hoặc: scripts/package.sh
make snapshot                                               # phiên bản 0.0.0-snapshot.<sha>, ra dist/snapshot

scripts/package.sh dựng binary tĩnh linux amd64 và arm64, chạy nfpm cho deb và rpm, tạo tar.gz, chép install.sh, ghi dist/release/SHA256SUMS. Biến: VERSION, COMMIT, DATE, OUT, NFPM. Nếu đặt SIGN_HOOK, script gọi $SIGN_HOOK <đường dẫn SHA256SUMS> và hook phải tạo SHA256SUMS.sig (ví dụ gpg --detach-sign -o SHA256SUMS.sig "$1"), thiếu tệp là lỗi. make checksums tính lại SHA256SUMS sau khi thay tệp thủ công (phải ký lại).

Cài đặt hàng loạt

Công cụ	Cách làm
Ansible	Role accesshub_agent (GĐ 2): thêm kho, cài gói, ghi cấu hình, enroll bằng license lấy từ vault, chạy status để kiểm tra. Windows dùng win_package
Puppet, Chef, Salt	Ví dụ manifest trong docs (GĐ 2)
cloud-init	Mẫu user-data cài gói và enroll ở lần khởi động đầu (xem dưới)
Windows GPO	Triển khai MSI qua Software Installation, token qua script khởi động đọc từ chia sẻ có ACL
SCCM, Intune	Ứng dụng MSI với dòng lệnh cài đặt im lặng, phát hiện bằng khóa registry hoặc sự hiện diện dịch vụ
Terraform	Truyền user_data hoặc custom_data tới máy ảo
Access Hub UI	Tạo License cho từng máy hoặc theo lô, hiển thị lệnh cài đặt sẵn để sao chép (HUB, xem collector 06)

Mẫu cloud-init:

#cloud-config
write_files:
  - path: /etc/accesshub-agent/license.token
    permissions: "0600"
    content: "ahet_xxx"
runcmd:
  - curl -fsSL https://downloads.example.com/agent/install.sh -o /tmp/install.sh
  - ACCESSHUB_COLLECTOR_URL=https://collector.example.com ACCESSHUB_LICENSE_FILE=/etc/accesshub-agent/license.token bash /tmp/install.sh

Khuyến nghị: License theo lô có max_uses = số máy dự kiến và hạn ngắn (ví dụ 24 giờ), không dùng token vô hạn.

Image mẫu và nhân bản VM

• Không enroll trong image gốc. Cài gói nhưng để dịch vụ chưa chạy (--no-start) hoặc để chưa có thông tin đăng nhập, enroll ở lần khởi động đầu qua cloud-init hoặc script.
• Nếu đã lỡ nhân bản: agent phát hiện machine_id đổi (xem 05), dừng gửi và ghi identity_mismatch. Xử lý: xóa credentials.json, đảm bảo machine-id mới (systemd-machine-id-setup), enroll lại. Windows: dùng sysprep (MachineGuid được tạo lại), xóa credentials.bin trong image.
• Mẫu script first-boot-enroll.sh và first-boot-enroll.ps1 (AGT-11).

Cập nhật

Giai đoạn 1 và 2: qua kênh gói

Cập nhật bằng kho gói hoặc công cụ triển khai. Đơn giản, dùng cơ chế sẵn có của quản trị viên, phù hợp doanh nghiệp có quy trình thay đổi.

Giai đoạn 3: tự cập nhật (tùy chọn theo công ty)

Bật bằng cấu hình từ xa hoặc cục bộ (auto_update: true), mặc định tắt ở các cài đặt hiện có.

Luồng:

1. Agent gọi GET /agent/v1/update?os=&arch=&version=&channel= (chu kỳ 1 giờ, jitter). Không có bản mới thì nhận 204.
2. Collector trả manifest ký Ed25519 (thông điệp UpdateManifest ở 10-wire-contract.md): version, url, sha256, signature_ed25519, min_version, rollout_percent, released_at.
3. Agent kiểm tra: chữ ký hợp lệ bằng khóa nhúng, version cao hơn và không nằm trong danh sách bị chặn, agent thuộc nhóm triển khai (hash(agent_id) mod 100 < rollout_percent).
4. Tải về thư mục tạm, kiểm tra sha256 và kích thước, kiểm tra chữ ký gói khi có.
5. Chạy accesshub-agent version của bản mới (kiểm tra khởi chạy được).
6. Thay thế nguyên tử: Linux đổi tên binary rồi restart qua systemd, Windows dùng helper nhỏ hoặc cơ chế dịch vụ (đổi tên tệp .old, dừng, thay, khởi động).
7. Bản mới phải gửi thành công một lô trong 5 phút. Nếu không, quay lui về bản cũ (giữ .old), báo cáo lỗi qua self-stats và đánh dấu phiên bản là lỗi trên collector.
8. Rollout theo đợt (1%, 10%, 50%, 100%), dừng khẩn cấp bằng cách hạ rollout_percent về 0 hoặc chặn phiên bản.

Ràng buộc: agent không tự thay đổi dịch vụ ngoài chính nó. Không hạ cấp trừ khi manifest ký cho phép (chống tấn công hạ cấp nhờ min_version trong manifest).

Gỡ cài

Việc	Linux	Windows
Gỡ, giữ dữ liệu	apt remove, dnf remove	Apps and Features, msiexec /x
Gỡ hoàn toàn	apt purge, hoặc accesshub-agent uninstall --purge	msiexec /x ... PURGE=1
Thông báo Access Hub	Giao thức không có lệnh tự hủy đăng ký: quản trị viên thu hồi hoặc đánh dấu ngừng giám sát agent trong Access Hub sau khi gỡ (agent im lặng sẽ báo agent_down cho đến khi làm bước này)	tương tự

Gỡ agent không xóa Server trong kiểm kê của Access Hub, chỉ đổi trạng thái giám sát.

Kiểm thử gói

Mỗi bản phát hành phải đạt (xem 08-testing.md): cài mới, nâng cấp từ N-1, gỡ, gỡ purge, cài lại sau gỡ, khởi động lại máy, trên toàn ma trận hệ điều hành chính thức. Với Windows: tài khoản dịch vụ, quyền thư mục, Event Log, cài im lặng, nâng cấp giữ cấu hình.