HyperVive

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 10 Open GitHub ↗

Wake-on-LAN and checkpoint watching service for Hyper-V guests

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# HyperVive

A service that performs utility functions for Hyper-V virtual machines

Current version: 3.5

## Version 3.5 BREAKING CHANGE

The generic IDs 4000, 4001, and 4002 have been deprecated and split out into the following sets:
  - 4000 (checkpoint-related job has started)
    - 4003: checkpoint apply started
    - 4006: checkpoint clear state started
    - 4009: checkpoint delete started
    - 4012: checkpoint creation started
  - 4001 (checkpoint-related job succeeded)
    - 4004: checkpoint apply succeeded
    - 4007: checkpoint clear state success
    - 4010: checkpoint delete success
    - 4013: checkpoint creation success
  - 4002 (checkpoint-related job failed)
    - 4005: checkpoint apply failed
    - 4008: checkpoint clear state failed
    - 4011: checkpoint delete failed
    - 4014: checkpoint creation failed

The service now installs as delayed start instead of instant start. In some cases, .Net does not initialize quickly enough on boot and it causes .Net-dependent services to fail to start. You can revert this to auto-start after install, if you prefer.

### Non-breaking changes

In previous versions the category of an event showed its internal number (e.g., 6 for anything checkpoint-related). Text labels now appear as intended. The category numbers themselves remain unchanged.

## Version 2.0 feature: Checkpoint Watcher

Want to know WHO created that Hyper-V checkpoint (formerly known as snapshots)? Now you can find out! HyperVive will watch for checkpointing events and record details. It records one event for the initiation of a checkpoint job and another when it completes.

### Checkpoint Watcher Technical Brief

Hyper-V uses WMI jobs behind the scenes for most of its activities. The job object contains details, including the user name of the individual that requested the job. So, HyperVive watches the WMI space for new jobs to appear. When one does, HyperVive checks to see if it has anything to do with a checkpoint. If it does, then HyperVive records the start of the event. It then watches for the event to end, and records the outcome of the job.

HyperVive will record events related to these types of WMI jobs:

- Checkpoint creation
- Checkpoint deletion
- Checkpoint application (revert)
- Clearing of a checkpoint's saved state

You will find these event entries in the host's regular Application event log.

## Version 1.0 feature: Wake-On-LAN

HyperVive intercepts wake-on-LAN frames and starts all matching virtual machines from Off, Saved, or Paused states.

### Wake-on-LAN Technical Brief

HyperVive maintains a local inventory of all virtual adapters connected to virtual machines (synthetic or emulated). It continually watches for adds, changes, and deletes. These events occur when virtual machines are created, migrated on or off the host, and when individual adapters are added, removed, or changed on virtual machines.

HyperVive listens on all _host_ network adapters (physical or virtual). This means that the management operating system does need a presence in all VLANs that might carry WOL frames. It cannot listen on VLANs that only virtual machines connect to.

Data flow:

1. HyperVive intercepts a WOL frame and validates its format
2. HyperVive compares the MAC in the WOL frame to to all known virtual adapter MACs
3. If any MACs match, HyperVive checks that the connecting virtual machine is in an Off, Saved, or Paused state
4. HyperVive starts any virtual machine that passes all of the previous checks
5. HyperVive logs matched WOL frames and the outcome of start events to the Application log

Newly-created virtual adapters set to use a dynamic MAC (like those on a newly-created VM) will have a MAC of 00:00:00:00:00:00. If HyperVive receives a WOL frame for that MAC, it will start all applicable VMs.

## Debug Mode

To instruct HyperVive to log detailed messages for troubleshooting, make the following registry change:

- **Path**: HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\HyperVive
- **Value name**: DebugMode
- **Value type**: DWORD
- **Value**: 1 for debug logging, 0 for minimal logging (default)

Changes take effect instantly; you do not need to restart the service. If you create and then delete the key, it will stay in its current mode until restarted.

### Use PowerShell to set Debug Mode

To enable in PowerShell:

```PowerShell
Set-ItemProperty -Path HKLM:\SYSTEM\CurrentControlSet\Services\HyperVive\ -Name DebugMode -Value 1
```

To disable in PowerShell:

```PowerShell
Set-ItemProperty -Path HKLM:\SYSTEM\CurrentControlSet\Services\HyperVive\ -Name DebugMode -Value 0
```

Changes take effect instantly; you do not need to restart the service.

## Installation and Removal Instructions

Use the latest SetupHyperVive.msi from the [Releases page](https://github.com/ejsiron/HyperVive/releases) to install, remove, or upgrade.

*NOTE*: The MSI can cleanly upgrade manually-installed instances of versions 1 and 2.

## HyperVive Event IDs

The following reference contains all HyperVive event ID codes and their basic meanings. Check the specific event for details.

- 1000: Unexpected application error
- 1001: Module-specific error
- 1011: Registry access error
- 1012: Registry key open error
- 1021: Invalid virtual adapter
- 1022: Virtual adapter subscriber error
- 1031: Wake-on-LAN receiver error
- 2000: Magic packet received and processed
- 3000: Successfully started a virtual machine
- 3001: Failed to start a virtual machine
- 4000: A checkpoint-related job has started (deprecated; previously logged 4000s will not disappear but no new ones will be logged)
- 4001: A checkpoint-related job succeeded (deprecated; previously logged 4001s will not disappear but no new ones will be logged)
- 4002: A checkpoint-related job failed (deprecated; previously logged 4002s will not disappear but no new ones will be logged)
- 4003: Checkpoint apply job started
- 4004: Checkpoint apply job succeeded
- 4005: Checkpoint apply job failed
- 4006: Checkpoint clear state job started
- 4007: Checkpoint clear state job succeeded
- 4008: Checkpoint clear state job failed
- 4009: Checkpoint delete job started
- 4010: Checkpoint delete job succeeded
- 4011: Checkpoint delete job failed
- 4012: Checkpoint create job started
- 4013: Checkpoint create job succeeded
- 4014: Checkpoint create job failed
- 9000: Non-specific debug message
- 9001: HyperVive's Debug mode changed
- 9002: Debug Mode registry key not found
- 9003: Enumerated virtual adapters (debug)
- 9004: A new virtual adapter was created (debug)
- 9005: A virtual adapter changed (debug)
- 9006: An update to a virtual adapter was intercepted, but HyperVive did not know it existed (debug)
- 9007: A virtual adapter was deleted (debug)
- 9008: HyperVive is trying to start a virtual machine (debug)
- 9009: Something that looked like a magic packet was received, but it turned out to be malformed (debug)
- 9010: Magic packet received, even if HyperVive chose not to process it (debug)
- 9011: MAC exclusion period ended (debug)
- 9012: Virtualization-related job intercepted (debug)

HyperVive

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README