# Hyper-V

# 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 remote mode or 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 (Hyper-V) running the plugin in local mode; Pandora FMS Server on Linux running the plugin in remote mode.</td></tr><tr><td>**Systems where it works**  
</td><td>Remote mode: any Linux system with connectivity to the Hyper-V host and plugin dependencies. 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
      }
    ]
  }
]
```

# Discovery

This plugin can be integrated with Pandora FMS Discovery.

To do so, you must upload the “.disco” package, which can be downloaded from the Pandora FMS library:

[https://pandorafms.com/library/](https://pandorafms.com/library/)

[![image.png](https://pandorafms.com/guides/public/uploads/images/gallery/2026-04/scaled-1680-/0aHimage.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2026-04/0aHimage.png)

Once uploaded, Hyper-V environments can be monitored by creating Discovery tasks from the *Management &gt; Discovery &gt; Applications* section

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

For each task, the following minimum parameters will be required:

- **Hyper-V IP:** IP address of the host with Hyper-V.
- **Credentials:** Custom-type username and password. To do this, you will need to create a new credential in the *Management &gt; Configuration &gt; Credential store* una nueva credencial.

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

It will also be possible to adjust the task configuration to customize the desired monitoring:

- **Scan Hypervisor** Will create an agent with modules for the hypervisor host.
- **Scan** **VM** Will perform the search to create different agents for the existing VMs.
- **Scan** **Networking** Will create modules for the network adapters of the different VMs.
- **Scan Storage** Will create modules for the different storage disks of the VMs.

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

# 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)