> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vms.verolabs.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup guideline VMS agent collector

> Hướng dẫn triển khai agent bằng script và cấu hình probe monitor

<div style={{ width: '100%', height: 4, marginBottom: 24, borderRadius: 2, background: 'rgba(0,0,0,0.08)' }}>
  <div style={{ width: '75%', height: '100%', borderRadius: 2, background: 'linear-gradient(90deg, var(--accent-primary) 0%, var(--accent-light) 50%, var(--accent-dark) 100%)' }} />
</div>

VMS agent collector chạy trên host khách hàng để thu thập metrics, checks và logs, sau đó gửi về VMS Master qua HTTPS.

## Mô hình hoạt động của Agent

<img src="https://mintcdn.com/vero-35a9bc05/YT70Sr2qWE1qMbL1/images/vms_agent_deployment.png?fit=max&auto=format&n=YT70Sr2qWE1qMbL1&q=85&s=82ca8c14ee2117bca418e5b907fc3ef7" alt="Cài đặt và kết nối VMS Agent" width="1024" height="1024" data-path="images/vms_agent_deployment.png" />

***

## Các đầu mục chuẩn bị (Agent)

| Đầu mục | Yêu cầu chuẩn bị                 |
| ------- | -------------------------------- |
| OS      | **Linux** hoặc **Windows**       |
| Kết nối | Outbound HTTPS tới `INGRESS_URL` |

***

## Quy trình triển khai trên Linux

<Steps>
  <Step title="1. Chạy script cài đặt">
    * **Step**: Trên host cần giám sát, chạy script (không cần sudo):
      ```bash theme={null}
      curl -fsSL "<agent.sh link>" | sh
      ```
    * **Check**: Script in tiến trình `Step 1/6 ... 6/6`.
    * **Result**: `SUCCESS (verified): vms-monitor-agent <version> installed`.

          <img src="https://mintcdn.com/vero-35a9bc05/3Jj1PaRU569Y86dW/images/agent-install/01-install.png?fit=max&auto=format&n=3Jj1PaRU569Y86dW&q=85&s=7ab245956f81f3a4257719964905e8e5" alt="Kết quả chạy script cài đặt agent trên Linux" width="4749" height="3007" data-path="images/agent-install/01-install.png" />
  </Step>

  <Step title="2. Kiểm tra service">
    * **Step**: Xem trạng thái service:
      ```bash theme={null}
      systemctl --user status vms-monitor-agent --no-pager
      ```
    * **Check**: Trạng thái hiển thị `active (running)`.
    * **Result**: Binary tại `~/.local/bin/vms-monitor-agent`, config tại `~/.config/vms-monitor-agent/agent.env`.

          <img src="https://mintcdn.com/vero-35a9bc05/3Jj1PaRU569Y86dW/images/agent-install/02-service-status.png?fit=max&auto=format&n=3Jj1PaRU569Y86dW&q=85&s=ce4a618ac51e29c863c654ca60aff863" alt="Trạng thái service vms-monitor-agent đang chạy" width="4016" height="1256" data-path="images/agent-install/02-service-status.png" />
  </Step>

  <Step title="3. Kiểm tra logs kết nối">
    * **Step**: Xem log thời gian thực:
      ```bash theme={null}
      journalctl --user -u vms-monitor-agent -f
      ```
    * **Check**: Tìm dòng log `agent started` kèm `agentKey`, `probes`, `configVersion`.
    * **Result**: Log dạng JSON xuất hiện, ví dụ:

      ```json theme={null}
      {"level":"INFO","msg":"agent started","agentKey":"web-01/appuser","configVersion":12,"probes":8}
      ```

          <img src="https://mintcdn.com/vero-35a9bc05/3Jj1PaRU569Y86dW/images/agent-install/03-logs.png?fit=max&auto=format&n=3Jj1PaRU569Y86dW&q=85&s=8d72095624b490ed9ed69037efdb3ffd" alt="Log JSON &#x22;agent started&#x22; trên Linux" width="5116" height="823" data-path="images/agent-install/03-logs.png" />
  </Step>
</Steps>

Sau khi cài xong, agent hiện trong **Agent Config (FLEET)** trên Dashboard (`https://<VMS_MASTER_IP>/dashboards/agent-config`):

<img src="https://mintcdn.com/vero-35a9bc05/3Jj1PaRU569Y86dW/images/agent-install/09-agent-online.png?fit=max&auto=format&n=3Jj1PaRU569Y86dW&q=85&s=9075bdca2e4a362b721763400194cc4a" alt="Agent online trong FLEET trên Dashboard" width="1397" height="896" data-path="images/agent-install/09-agent-online.png" />

***

## Quy trình triển khai trên Windows

<Steps>
  <Step title="1. Chạy script cài đặt">
    * **Step**: Mở PowerShell (không cần quyền Administrator):
      ```powershell theme={null}
      irm "<agent.ps1 link>" | iex
      ```
    * **Check**: Script in tiến trình `Step 1/6 ... 6/6`.
    * **Result**: `SUCCESS (verified): vms-monitor-agent <version> installed`.
  </Step>

  <Step title="2. Kiểm tra trạng thái agent">
    * **Step**: Kiểm tra task auto-start và tiến trình agent:
      ```powershell theme={null}
      Get-ScheduledTask -TaskName vms-monitor-agent
      Get-Process vms-monitor-agent
      ```
    * **Check**: Task tồn tại và có process agent đang chạy.
    * **Result**: Binary tại `%LOCALAPPDATA%\vms-monitor-agent\vms-monitor-agent.exe`.
  </Step>

  <Step title="3. Kiểm tra logs / version">
    * **Step**: In phiên bản:
      ```powershell theme={null}
      & "$env:LOCALAPPDATA\vms-monitor-agent\vms-monitor-agent.exe" version
      ```
    * **Check**: In ra version, commit và build date.
    * **Result**: Agent đang online trên Dashboard.
  </Step>
</Steps>

***

## Quản lý agent bằng dòng lệnh

Sau khi cài, mở **terminal/PowerShell mới** và dùng lệnh `vms-monitor-agent` (không cần `sudo`/Administrator).

| Lệnh                          | Tác dụng                                                       |
| ----------------------------- | -------------------------------------------------------------- |
| `vms-monitor-agent status`    | Xem trạng thái: đã cài / đang chạy / auto-start / version      |
| `vms-monitor-agent start`     | Khởi động và bật tự chạy lại khi đăng nhập/khởi động máy       |
| `vms-monitor-agent stop`      | Dừng **hẳn** và tắt auto-start — agent **sẽ không tự dậy lại** |
| `vms-monitor-agent restart`   | Khởi động lại, giữ nguyên auto-start                           |
| `vms-monitor-agent uninstall` | Tự gỡ agent (thêm `--purge` để xoá cả state)                   |
| `vms-monitor-agent version`   | In version, commit, build date                                 |
| `vms-monitor-agent help`      | In hướng dẫn sử dụng đầy đủ                                    |

Lệnh `status` cho biết agent đã cài / đang chạy / auto-start / version:

<img src="https://mintcdn.com/vero-35a9bc05/3Jj1PaRU569Y86dW/images/agent-install/04-agent-status.png?fit=max&auto=format&n=3Jj1PaRU569Y86dW&q=85&s=2c022e5d79cb9996c35ff86a3d08038d" alt="Kết quả lệnh vms-monitor-agent status" width="2649" height="966" data-path="images/agent-install/04-agent-status.png" />

Minh hoạ `stop` (dừng hẳn) rồi `start` lại — chú ý `running` và `auto-start` đổi trạng thái theo:

<img src="https://mintcdn.com/vero-35a9bc05/3Jj1PaRU569Y86dW/images/agent-install/05-lifecycle.png?fit=max&auto=format&n=3Jj1PaRU569Y86dW&q=85&s=cc342ea7d18c67a8282018207af47d08" alt="Vòng đời stop và start agent" width="3782" height="1620" data-path="images/agent-install/05-lifecycle.png" />

<Info>
  **`stop` là dừng hẳn**: dừng tiến trình và tắt auto-start. Agent **không tự chạy lại sau reboot**. Dùng `start` để chạy lại hoặc `uninstall` để gỡ.

  Nếu gặp `command not found`, mở shell mới hoặc dùng đường dẫn đầy đủ (`~/.local/bin/vms-monitor-agent` trên Linux, `%LOCALAPPDATA%\vms-monitor-agent\vms-monitor-agent.exe` trên Windows).
</Info>

***

## Cập nhật agent

Chạy lại lệnh cài đặt:

* **Linux**:

  ```bash theme={null}
  curl -fsSL "<agent.sh link>" | sh
  ```

  Script so sánh phiên bản và hỏi trước khi thay binary.

  Nếu đã ở bản mới nhất, script báo `already current`:

  <img src="https://mintcdn.com/vero-35a9bc05/3Jj1PaRU569Y86dW/images/agent-install/07-update.png?fit=max&auto=format&n=3Jj1PaRU569Y86dW&q=85&s=042b2baebd5fa52dd6fcdc3905415885" alt="Chạy lại lệnh cài khi agent đã ở bản mới nhất" width="3782" height="2132" data-path="images/agent-install/07-update.png" />

* **Windows**:
  ```powershell theme={null}
  irm "<agent.ps1 link>" | iex
  ```

***

## Gỡ cài đặt agent

Chạy `uninstall` từ binary, hoặc tải lại script kèm `uninstall`:

* **Linux**:

  ```bash theme={null}
  # Gỡ ngay trên máy bằng binary; thêm --purge để xoá cả state:
  vms-monitor-agent uninstall
  # Hoặc, nếu host chưa có lệnh này, tải lại script:
  curl -fsSL "<agent.sh link>" | sh -s -- uninstall
  ```

  <img src="https://mintcdn.com/vero-35a9bc05/3Jj1PaRU569Y86dW/images/agent-install/06-uninstall.png?fit=max&auto=format&n=3Jj1PaRU569Y86dW&q=85&s=e7f4bfd0663d478ab64327cc4a11695d" alt="Gỡ agent bằng lệnh vms-monitor-agent uninstall" width="3482" height="1113" data-path="images/agent-install/06-uninstall.png" />

* **Windows**:
  ```powershell theme={null}
  # Gỡ ngay trên máy bằng binary; thêm --purge để xoá cả thư mục cài:
  vms-monitor-agent uninstall
  # Hoặc tải lại script:
  & ([scriptblock]::Create((irm "<agent.ps1 link>"))) uninstall
  ```

***

## Troubleshooting thường gặp

| Triệu chứng           | Nguyên nhân thường gặp     | Cách xử lý                                   |
| --------------------- | -------------------------- | -------------------------------------------- |
| Agent start fail ngay | Thiếu ingress URL/API key  | Kiểm tra log agent để xem lỗi chi tiết       |
| `401`/auth blocked    | API key sai hoặc bị rotate | Lấy key mới từ VMS Master và chạy lại script |