# Hyper-V Windows

# Introduction

The Hyper-V plugin for Pandora FMS discovers the Hyper-V host and its virtual machines, collecting status and performance metrics (CPU, memory, network, and storage) to create the corresponding monitoring modules. It can run in local mode on the Hyper-V server itself, generating a JSON with the definition of agents and modules for later use.

# Compatibility matrix

<table border="1" id="bkmrk-systems-where-it-has" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>**Systems where it has been tested**  
</td><td>Windows Server 2022 (Hyper-V) running the plugin in local mode.</td></tr><tr><td>**Systems where it works**  
</td><td>Local mode: Windows Server with Hyper-V (and PowerShell) where the `.exe` / script is executed.</td></tr></tbody></table>

# Prerequisites

- Connectivity to Hyper-V from Pandora

The plugin is a binary that contains the dependencies packaged, so no installation of any kind of dependency is required for its use.

- Permissions

**Configure WinRM**  
`Enable-PSRemoting -Force -SkipNetworkProfileCheck`  
`winrm quickconfig -force`  
`winrm set winrm/config/service/auth '@{Basic="true"}'`  
`winrm set winrm/config/service '@{AllowUnencrypted="true"}'`  
`winrm set winrm/config/service '@{MaxTimeoutms="600000"}'`

**Allow HTTP 401**  
`reg add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System" /v LocalAccountTokenFilterPolicy /t REG_DWORD /d 1 /f`

**Allow WinRM Firewall**  
`New-NetFirewallRule -DisplayName "WinRM HTTP In" -Direction Inbound -Protocol TCP -LocalPort 5985 -Action Allow -Profile Any -Force`

**Restart services**  
`Restart-Service WinRM -Force`  
`Start-Service vmms`

**Check all**  
`winrm get winrm/config/service/auth`  
`Get-VM`

- Install the **hv-kvp-daemon** service on VMs with Linux systems so that they report all modules.

# Parameters and configuration

**Parameters**

<table border="1" id="bkmrk---help-message-with-" style="border-collapse: collapse; width: 100%; height: 158.375px;"><colgroup><col style="width: 50.0618%;"></col><col style="width: 50.0618%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><td style="height: 29.7969px;">--help</td><td style="height: 29.7969px;">Message with the parameters</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">--confg</td><td style="height: 29.7969px;">Path to the configuration file</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">--execute\_local</td><td style="height: 46.5938px;">Parameter to indicate that it will be executed from the Hyper-V host itself and not from the Pandora server.</td></tr><tr style="height: 52.1875px;"><td style="height: 52.1875px;">--save\_file</td><td style="height: 52.1875px;">Parameter that requires --execute\_local in order to be used. This parameter will save the JSON output to a file `.txt`

</td></tr></tbody></table>

<div class="flex flex-col text-sm pb-25" id="bkmrk-configuration-file-%28"><section class="text-token-text-primary w-full focus:outline-none [--shadow-height:45px] has-data-writing-block:pointer-events-none has-data-writing-block:-mt-(--shadow-height) has-data-writing-block:pt-(--shadow-height) [&:has([data-writing-block])>*]:pointer-events-auto scroll-mt-[calc(var(--header-height)+min(200px,max(70px,20svh)))]" data-scroll-anchor="true" data-testid="conversation-turn-36" data-turn="assistant" data-turn-id="request-WEB:5b758fa1-11ad-4bb8-b3bb-31497473c607-17" dir="auto">**Configuration file (--conf)**

```
agent_prefix = HyperV
agents_group_id = 2
scan_vm = 1
scan_networking = 1
scan_storage = 0
scan_hypervisor = 1
```

</section></div>

# Manual execution

The format for executing the plugin is as follows:

```
.\pandora_hyperV.exe --conf < ruta del .conf > --execute_local
```

Example:

```
.\pandora_hyperV.exe --conf pandora_hyperv.conf --execute_local
```

Example getting .txt with JSON

```
.\pandora_hyperV.exe --conf pandora_hyperv.conf --execute_local --save_file
```

Example output JSON:

```
[
  {
    "agent_data": {
      "agent_name": "HyperV WIN-BKM50GV4DF9",
      "agent_alias": "HyperV WIN-BKM50GV4DF9",
      "os": "Windows",
      "os_version": "Windows Server",
      "interval": 300,
      "id_group": 2,
      "address": "WIN-BKM50GV4DF9",
      "description": "Hyper-V host WIN-BKM50GV4DF9 (WIN-BKM50GV4DF9)"
    },
    "module_data": [
      {
        "name": "HyperV Local Status",
        "type": "generic_proc",
        "data": 1,
        "description": "Hyper-V plugin running locally (1=OK, 0=Fail)"
      }
    ]
  },
  {
    "agent_data": {
      "agent_name": "HyperV ubuntu server",
      "agent_alias": "HyperV ubuntu server",
      "os": "Windows",
      "os_version": "Windows",
      "interval": 300,
      "id_group": 2,
      "address": "WIN-BKM50GV4DF9",
      "description": "VM ubuntu server on Hyper-V host WIN-BKM50GV4DF9"
    },
    "module_data": [
      {
        "name": "State",
        "type": "generic_data",
        "data": 3,
        "description": "VM state: 2=Running 3=Off 32768=Paused 32769=Saved 32770=Starting 32771=Stopping 32772=Pausing 32773=Resuming 32774=Saving 32775=FastSaved 0=Unknown. Current: Off",
        "min_critical": 3,
        "max_critical": 3.1
      }
    ]
  }
]
```

# Agents and modules generated by the plugin

With the **Scan hypervisor** token the plugin creates:

- **Agents created:** **1 agent** for the **Hyper‑V host** (the hypervisor). Its name is typically `HyperV <ComputerName>` if an agent prefix is configured, or `<ComputerName>` if no prefix is provided.
- **Modules created (host agent):**
    - **HyperV Connection Status** (remote mode) / **HyperV Local Status** (local mode): execution/connectivity status of the discovery run.
    - **Host Memory Total (GB)**: total memory on the Hyper‑V host.
    - **Host Memory Free (GB)**: free/available memory on the Hyper‑V host.

With the **Scan VM** token the plugin creates:

- **Agents created:** **1 agent per virtual machine** discovered on the Hyper‑V host (e.g., `HyperV <VMName>` if an agent prefix is set, or `<VMName>` if no prefix is provided).
- **Modules created (per VM agent):**
    - **State**: VM numeric state.
    - **Status**: VM operational status reported by Hyper‑V (string).
    - **Generation**: VM generation.
    - **CPU usage percentage**: VM CPU usage in percent (description cleaned, without “from Get‑VM”).
    - **Memory** (when available): VM memory metrics (assigned/consumed/dynamic depending on what is exposed).
    - **Uptime**: VM uptime in seconds.

With the **Scan Networking** token the plugin creates:

- **Agents created:** it does **not** create new agents; it **adds networking modules** to the **already discovered VM agents** (it requires the VM agents to exist).
- **Modules created (per VM, per network adapter):**
    - Adapter **connectivity/state** modules (connected / disconnected).
    - The associated **Virtual Switch** (vSwitch) information.
    - **MAC Address** information (when exposed as a module/value in your version).
    - Adapter **status** as reported by Hyper‑V.
- **Multiple adapters with the same name:** if a VM has 2+ NICs sharing the same `Name` (e.g., “Network Adapter”), the plugin appends a suffix to avoid overwriting modules: `..._1`, `..._2`, etc. If the adapter name is unique, no numbering is added.

With the **Scan Storage** token the plugin creates:

- **Agents created:** it does **not** create new agents; it **adds storage-related modules** to the **VM agents** (and/or the hypervisor agent if your configuration includes host storage metrics).
- **Modules created (per VM):**
    - Modules for **disks/volumes** reported for the VM (size/usage/status depending on the available data).
    - When usage is reported per drive letter, module names follow the pattern **`DiskUsed_<LETTER>`** (e.g., `DiskUsed_C`, `DiskUsed_D`, …) instead of labels like “Disk C Used GB”.
- **Purpose:** to monitor disk usage and detect low space or abnormal growth on virtual machines.

<div class="flex flex-col text-sm pb-25" id="bkmrk-an-example-of-agents"><section class="text-token-text-primary w-full focus:outline-none [--shadow-height:45px] has-data-writing-block:pointer-events-none has-data-writing-block:-mt-(--shadow-height) has-data-writing-block:pt-(--shadow-height) [&:has([data-writing-block])>*]:pointer-events-auto scroll-mt-[calc(var(--header-height)+min(200px,max(70px,20svh)))]" data-scroll-anchor="true" data-testid="conversation-turn-52" data-turn="assistant" data-turn-id="request-WEB:5b758fa1-11ad-4bb8-b3bb-31497473c607-25" dir="auto">An example of agents created with the plugin would be the following:

</section></div>[![Agentes.png](https://pandorafms.com/guides/public/uploads/images/gallery/2026-04/scaled-1680-/6H5agentes.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2026-04/6H5agentes.png)

The hypervisor host modules will be as follows:

<div class="flex flex-col text-sm pb-25" id="bkmrk--1"><section class="text-token-text-primary w-full focus:outline-none [--shadow-height:45px] has-data-writing-block:pointer-events-none has-data-writing-block:-mt-(--shadow-height) has-data-writing-block:pt-(--shadow-height) [&:has([data-writing-block])>*]:pointer-events-auto scroll-mt-[calc(var(--header-height)+min(200px,max(70px,20svh)))]" data-scroll-anchor="true" data-testid="conversation-turn-52" data-turn="assistant" data-turn-id="request-WEB:5b758fa1-11ad-4bb8-b3bb-31497473c607-25" dir="auto">[![hyper v.png](https://pandorafms.com/guides/public/uploads/images/gallery/2026-04/scaled-1680-/GChhyper-v.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2026-04/GChhyper-v.png)

[![detallados hyperV.png](https://pandorafms.com/guides/public/uploads/images/gallery/2026-04/scaled-1680-/6Yydetallados-hyperv.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2026-04/6Yydetallados-hyperv.png)

</section></div>For a Windows VM, we can see that the following modules are created:

[![modulos windows.png](https://pandorafms.com/guides/public/uploads/images/gallery/2026-04/scaled-1680-/UOnmodulos-windows.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2026-04/UOnmodulos-windows.png)

[![detallados windows.png](https://pandorafms.com/guides/public/uploads/images/gallery/2026-04/scaled-1680-/sVXdetallados-windows.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2026-04/sVXdetallados-windows.png)

For an Ubuntu VM, we can see the following modules:

[![modulos ubuntu.png](https://pandorafms.com/guides/public/uploads/images/gallery/2026-04/scaled-1680-/NZnmodulos-ubuntu.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2026-04/NZnmodulos-ubuntu.png)

[![detallados ubuntu.png](https://pandorafms.com/guides/public/uploads/images/gallery/2026-04/scaled-1680-/RIfdetallados-ubuntu.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2026-04/RIfdetallados-ubuntu.png)