Bindplane

The Bindplane Developer Hub

Welcome to the Bindplane developer hub. You'll find comprehensive guides and documentation to help you start working with Bindplane as quickly as possible, as well as support if you get stuck. Let's jump right in!

Microsoft Hyper-V

Monitor Windows Hyper-V Hypervisor Servers

Supported Versions

Hyper-V Role configured on all Editions of:
Windows Server 2012
Windows Server 2016

Network Requirements

Ports: 5985 (HTTP) or 5985 (HTTPS) TCP, access to the Hyper-V server being monitored.

Setup Windows Remote Management (WinRM)

WinRM is required to collect Microsoft Hyper-V data.

Basic Setup

To complete basic WinRM setup, run the following commands:

winrm quickconfig -q
winrm set winrm/config/winrs @{MaxMemoryPerShellMB="300"}
winrm set winrm/config @{MaxTimeoutms="1800000"}
winrm set winrm/config/service/auth @{Basic="true"}

Non-SSL users can use the following additional commands to complete their basic setup:

Enabling SSL

SSL user should skip the following command and continue to Enabling SSL.

winrm set winrm/config/service @{AllowUnencrypted="true"}

Kerberos Setup

To complete a Kerberos WinRM setup, run the following commands:

winrm quickconfig -q
winrm set winrm/config/winrs @{MaxMemoryPerShellMB="300"}
winrm set winrm/config @{MaxTimeoutms="1800000"}
winrm set winrm/config/service/auth @{Kerberos="true"}

Non-SSL users can use the following additional commands to complete their Kerberos setup:

Enabling SSL

SSL users should skip the following command and continue to Enabling SSL.

winrm set winrm/config/service @{AllowUnencrypted="true"}

Enabling SSL

To enableSSL for either your Basic or Kerberos WinRM setups, perform the following steps:

Prerequisites
If you are using SSL and are fine with a self-signed certificate, we recommend using Ansible's WinRM setup script (github):

Invoke-Expression ((New-Object System.Net.Webclient).DownloadString('https://raw.githubusercontent.com/ansible/ansible/devel/examples/scripts/ConfigureRemotingForAnsible.ps1'))

To use a signed certificate, perform the following steps:

  1. Generate an SSL certificate from your internal certificate authority.

Note

Make sure to generate a P12 file.

  1. Copy the SSL certificate to the Windows Server.
  2. Import the SSL certificate:
    • Run mmc.exe
    • Select File > Add/Remove Snap-in.
    • From the list of available snap-ins, select Certificates, then click Add.
    • Select Computer account, then click Next.
    • Click Finish.
    • Verify that the certificate is installed in Console Root > Certificates (Local Computer > Personal > Certificates and Console Root > Certificates ( Local Computer) > Trusted Root Certification Authorities > Certificates.
  3. Verify your root certificate authority is installed in the Trusted Root Certification Authorities folder.
  4. Record the thumbprint of the certificate.
  5. Run the following commands to create a new WinRM listener with the certificate. The certificate should have no spaces.
winrm delete winrm/config/Listener?Address=*+Transport=HTTPS
winrm create winrm/config/Listener?Address=*+Transport=HTTPS @{Hostname="<FQDN>"; CertificateThumbprint="<COPIED_CERTIFICATE_THUMBPRINT>"}

To use a custom port, you can modify the above commands as follows:

winrm delete winrm/config/Listener?Address=*+Transport=HTTPS
winrm create winrm/config/Listener?Address=*+Transport=HTTPS @{Port="14539";Hostname="<FQDN>"; CertificateThumbprint="<COPIED_CERTIFICATE_THUMBPRINT>"}

Increasing WinRM Resources

Windows 2012 will only allow 30 shells per user. If other monitoring processes are using the same credentials, you may wish to increase this umber by running the following command:

winrm set winrm/config/winrs @{MaxShellsPerUser="100000"}

Testing WinRM

To test PowerShell connectivity, run the command test-wsman <ip>.

To start a remote PowerShell session, run the following command:

$options=New-PSSessionOption -SkipCACheck -SkipCNCheck Enter-PSSession -ComputerName <IP or host name> -Credential <user name> -UseSSL -Authentication <authtype> -SessionOption $options

Note

Replace <user name> with your Windows domain user name and <authtype> with the appropriate authentication type: Basic, Digest, Kerberos, or Negotiate.

Setting Microsoft Hyper-V Least-privileged User

Prerequisites

  • Prior to setting the LPU for Hyper-V, **ensure you have completed setting up Windows Remote Management (WinRM).
  • Create a new Windows user (domain or local) that you want to use for your LPU.

Procedure

On each Local Machine, perform the following steps:

  1. Right-click on the Start menu, then select Computer Management.
  2. In the window that appears, expand System Tools > Local Users and Groups > Groups.
  1. Right-click on Remote Management Users, then select Properties.
  2. In the Properties dialog that appears, click Add.
  1. Add your newly created least-privileged user as shown in the window below, then click OK.
  1. Repeat steps 3 - 5 twice more, adding your LPU to the Hyper-V Monitor Users and Performance Monitor Users group as well.

Assigning WMI Permissions

  1. Back in the Computer Management window, under Service and Applications, right-click on WMI Control, then select Properties from the pop-up menu.
  1. In the WMI Control Properties window, select the Security Tab, then select Root and click the Security button.
  1. In the Security for Root window, click the Advanced button
  1. In the Advanced Security Setting for Root window, click the Add button.
  1. In the Permission Entry for Root window, select the following:
  • For the Principal field, click Select a Principal, then add the Windows user you created previously.
  • For the Applies to field, ensure "This namespaces and subnamespaces" is selected.
  • Under Permissions, select Execute Methods, Enable Account, and Remote Enable.
  • Click OK to save the permissions for your LPU.

Adding a User to the WinRM SDDL

  1. From an administrator command prompt, run:
winrm configSDDL default
  1. In the dialog that appears, add the user, giving them Read and Execute permissions. Click OK.
  2. Restart the Windows Remote Management service for the changes to take effect (we recommend using the command line, as follows):
sc stop winrm
REM
sc queryex winrm
sc start winrm

REM Stopped

Ensure REM reports as "STOPPED". If it does not, troubleshoot WinRM below.

Troubleshooting WinRM

If the Windows Remote Management service does not properly stop, perform the following:

  1. Run the following command, recording the PID:
sc queryex winrm
  1. Run the following command to kill off the WinRM service:
taskkill /f /pid [PID]
  1. Run the following command to restart the WinRM service:
sc start winrm

Connection Parameters

Name
Required?
Description

Host

Required

The Hyper-V host to connect to.

Port

The port to use for WinRM connection to Hyper-V host.

Username

Required

Password

Required

SSL Configuration

The SSL mode to use when connecting to the target. Can be configured to not use SSL (No SSL), use SSL but do not verify the target's certificate (No Verify), and use SSL and verify the target's certificate (Verify).

Authentication Type

The authentication method used while making a WinRM connection to the Hyper-V host.

Domain

The domain used when using Kerberos authentication.

KRB5 File Location

Custom krb5.conf file to use when using Kerberos authentication.

Endpoint Prefix

Custom winrm endpoint prefix.

Connection Timeout

The number of seconds to allow for the API to return a response.

Concurrency Level

The number of remote PowerShell commands that will be run at the same time.

Metrics

Hard Disk

Name
Description

Alignment

Alignment of the Virtual Hard Disk.

Attached

Attached state of the Virtual Hard Disk.

Average Latency (Milliseconds)

Average latency of the Virtual Hard Disk.

Average Normalized IO Rate (per Second)

Average normalized IOPS of the Virtual Hard Disk.

Block Size (Bytes)

Block size of the Virtual Hard Disk.

Data Read (Bytes)

Amount of data read from the Virtual Hard Disk.

Data Written (Bytes)

Amount of data written to the Virtual Hard Disk.

Disk Identifier

Disk identifier of the Virtual Hard Disk.

Disk Usage (%)

Percentage of storage used on the Virtual Hard Disk.

File Size (Bytes)

File size on the Host of the Virtual Hard Disk.

Fragmentation Ratio (%)

Fragmentation percentage of the Virtual Hard Disk.

ID

Resource ID of the Virtual Hard Disk.

Logical Sector Size (Bytes)

Logical sector size of the Virtual Hard Disk.

Minimum Size (Bytes)

Minimum size of the Virtual Hard Disk.

Parent Path

Parent path of the Virtual Hard Disk.

Path

Path of the Virtual Hard Disk.

Physical Sector Size (Bytes)

Physical sector size of the Virtual Hard Disk.

Storage Capacity (Bytes)

Storage capacity of the Virtual Hard Disk.

VHD Format

VHD format of the Virtual Hard Disk.

VHD Type

VHD type of the Virtual Hard Disk.

Virtual Machine ID

The Virtual Machine ID that the disk is attached to.

Host

Name
Description

Cluster Group Name

Name of the Cluster Group that the Host is a member of.

Free Memory (Bytes)

Available memory of the Host.

ID

Resource ID of the Host.

IPv4 Addresses

Host IPv4 Addresses.

IPv6 Addresses

Host IPv6 Addresses.

Logical Processor Count

Logical processor count of the Host.

Memory Pressure (%)

Average VM Memory pressure of the Host.

Memory Utilization (%)

Memory utilization of the Host.

Migration Enabled

Whether migration is enabled for the Host.

Name

Name of the Host.

Processor DPC Rate (per Second)

The rate at which the processor receives and services DPCs.

Processor DPC Time (%)

The percentage of time the processor on the host spends receiving and services DPCs.

Processor Idle Time (%)

The percentage of time the processor on the host spends idle.

Processor Interrupt Rate (per Second)

The amount of processor interrupts every second on the host.

Processor Interrupt Time (%)

The percentage of time the processor on the host spends on interrupts.

Processor Privileged Time (%)

Total processor time spent by the kernal of the Host.

Processor Time (%)

Total processor time of the Host.

Processor User Time (%)

Total processor time spent other than the kernal of the Host.

Total Memory (Bytes)

Total memory of the Host.

Used Memory (Bytes)

Used memory of the Host.

VM Count

Total virtual machine count for the Host.

VM Off Count

Powered off virtual machine count for the Host.

VM On Count

Powered on virtual machine count for the Host.

Network Adapter

Name
Description

Adapter ID

ID of the Adapter.

Connected

Whether the network adapter is connected or not.

ID

Resource ID of the Network Adapter.

IP Addresses

List of IP Addresses attached to the Network Adapter.

MAC Address

MAC Address of the Network Adapter.

Status Descriptions

Status descriptions of the Network Adapter.

Switch ID

ID of the Network Adapter's switch.

Switch Name

Name of the Network Adapter's switch.

VM ID

ID of the attached Virtual Machine.

Virtual Machine

Name
Description

Aggregated Disk Data Read (Bytes)

Aggregated data read for all disks on the Virtual Machine

Aggregated Disk Data Written (Bytes)

Aggregated data written for all disks on the Virtual Machine

Average Disk Latency (Microseconds)

Average Disk Latency for all disks on the Virtual Machine

Average Memory Pressure (%)

This is a calculation of how much memory the VM wants divided by the amount of memory the VM currently has and then multiplied by 100.

Average Normalized IO Rate (per Second)

Average Normalized IOPS for all disks on the Virtual Machine

Boot Order

Boot order for the Virtual Machine.

CPU Usage (%)

CPU Usage of the Virtual Machine.

Dynamic Memory Buffer (%)

Specifies how much memory Hyper-V will attempt to assign to the virtual machine compared to the amount of memory actually needed by the applications and services running inside the virtual machine.

Dynamic Memory Enabled

Dynamic memory enabled on the Virtual Machine.

Dynamic Memory Maximum (Bytes)

Maximum memory of the Virtual Machine.

Dynamic Memory Minimum (Bytes)

Minimum memory of the Virtual Machine.

Generation

Generation version of the Virtual Machine

Host CPU Usage (%)

The amount of Host CPU used by this VM

ID

Resource ID of the Virtual Machine.

Inbound Traffic (Bytes)

Inbound traffic to the Virtual Machine.

IP Addresses

IP Addresses of the Virtual Machine.

Last Snapshot

Last snapshot time for the Virtual Machine.

MAC Addresses

MAC Addresses of the Virtual Machine.

Memory Assigned (Bytes)

Memory assigned on the Virtual Machine.

Memory Demand (Bytes)

Memory demanded by this Virtual Machine.

Memory Status

Status of physical memory able to be assigned to this Virtual Machine.

Memory Utilization (%)

Percentage of memory used on the Virtual Machine

Name

Name of the Virtual Machine.

Outbound Traffic (Bytes)

Outbound traffic from the Virtual Machine.

Processor Count

Processor count of the Virtual Machine.

Secure Boot

Secure boot for the Virtual Machine.

Snapshot Count

Count of all snapshots for the Virtual Machine.

Snapshot IDs

List of the IDs of snapshots from this vm.

Startup Memory (Bytes)

Startup memory of the Virtual Machine.

State

State of the Virtual Machine.

Status

Status of the Virtual Machine.

Target Memory Pressure Average (%)

This is a calculation of the target average memory pressure.

Time Since Last Snapshot (Days)

The number of days since the last snapshot.

Total Disk Allocation (Bytes)

Total disk allocation of the Virtual Machine on the Host.

Total Disk Usage (%)

Total percentage of all storage used that is attached to the Virtual Machine

Total Snapshot Size (Bytes)

Total size of all snapshots for the Virtual Machine.

Uptime (Seconds)

Uptime of the Virtual Machine.