Access Hyper-V VMs Without Network Setup

Need to access a Hyper-V virtual machine that has no network connectivity? Whether you're debugging an isolated system, working in a secure environment, or dealing with network configuration issues, remote access without network can be challenging with existing tools.

Microsoft provides several built-in solutions, but each has significant limitations. Here's a comprehensive guide to networkless Hyper-V access, including a new unified solution that works consistently across Windows and Linux VMs.

When You Need Networkless VM Access

Remote access to virtual machines without network connectivity is useful in several practical scenarios:

• Initial VM setup - Access newly created VMs instantly before configuring networking
• Automation and scripting - Build reliable scripts that work regardless of network state, using VM names instead of IP addresses
• Dynamic IP environments - Consistent access when VMs get different IPs from DHCP or after reboots
• Rapid development cycles - Quick access to frequently created/destroyed VMs without tracking changing IP addresses
• Network troubleshooting - Fix misconfigured networking when you can't connect normally

Additionally, especially during development, it's useful to sync files between host and VM - this is much more reliable when it works without requiring credentials or network setup.

While Hyper-V includes several tools for this scenario, none work reliably across all situations.

Current Solutions and Their Limitations

Before exploring better options, let's understand what's available today and why it's frustrating:

Existing Hyper-V Remote Access Tools

*Copy-VMFile often broken on Linux - Ubuntu's hv-fcopy-daemon service fails to start properly

Why Each Tool Falls Short

PowerShell Direct Excellent shell access: Enter-PSSession -VMName "VMName"
Windows VMs only - no Linux support
File transfers extremely slow vs. network methods

Copy-VMFile Simple file transfer: Copy-VMFile -VMName "VM" -SourcePath "C:\source.txt"
No shell access whatsoever
Frequently fails on Linux VMs due to integration service issues

hvc ssh SSH over Hyper-V sockets for Linux VMs
Requires complex guest configuration and setup
Doesn't work reliably across all Linux distributions
Windows support needs OpenSSH modifications (not yet available)

While hvc ssh could eventually solve these issues, we needed a solution that works today. So we developed a way to address these limitations while also eliminating the need to set up users for VM access.

The Solution: eryph Guest Services (EGS)

To solve these limitations, we developed eryph Guest Services (EGS) for eryph - a unified solution that provides SSH access to both Windows and Linux VMs without network connectivity.

Key Advantages of EGS

Standard SSH interface: Uses familiar SSH commands with generated aliases:

ssh <VM-ID>.hyper-v.alt           # Connect to standalone VM
ssh <catlet-name>.eryph.alt       # Connect to eryph catlet
ssh vmhostname                    # using a custom alias

Installing and Using EGS

Prerequisites

• Host system: Windows 10/11 or Windows Server with Hyper-V installed
• Guest VMs: Windows or Linux virtual machines
• PowerShell 7: Required for PowerShell remoting features (optional)

Installation Steps

Step 1: Guest VM Setup (Standalone Hyper-V Only)

If using eryph catlets: Guest services are preinstalled in recent base catlets, but can also be added as a gene to custom catlets.

If using standalone Hyper-V: Install guest services in each VM:

Download installation ISO from releases.dbosoft.eu, mount ISO in your VM and run:

# Windows (as Administrator)
D:\install.ps1

# Linux (as root)
sudo /media/cdrom/install.sh

Step 2: Install Host Tool (Required for Both Use Cases)

Install the EGS host tool and initialize configuration on your Windows host:

# Install egs-tool (as Administrator)
iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/eryph-org/guest-services/main/src/Eryph.GuestServices.Tool/install.ps1'))

# Initialize host configuration
egs-tool initialize

Step 3: Configure SSH Access

Add VM to SSH configuration and update:

# Add VM to SSH configuration  
egs-tool add-ssh-config <VM-ID> [optional-alias]

# Update SSH config
egs-tool update-ssh-config

Basic Usage Examples

SSH shell access:

# Connect using generated aliases
ssh <VM-ID>.hyper-v.alt           # Standalone Hyper-V
ssh <catlet-name>.eryph.alt       # eryph catlets

# Or with custom alias
ssh myvm                          # If you set a custom alias

# Run single commands
ssh myvm "systemctl status apache2"    # Linux command
ssh winvm "Get-Service"                # Windows PowerShell

File transfer capabilities: EGS includes comprehensive file transfer functionality:

# Upload single file
egs-tool upload-file <VM-ID> C:\local\file.txt /remote/path/file.txt

# Upload directory (non-recursive)
egs-tool upload-directory <VM-ID> C:\local\folder /remote/path/folder

# Upload directory with subdirectories
egs-tool upload-directory <VM-ID> C:\local\folder /remote/path/folder --recursive

# Download single file
egs-tool download-file <VM-ID> /remote/path/file.txt C:\local\file.txt

# Download directory (non-recursive)
egs-tool download-directory <VM-ID> /remote/path/folder C:\local\folder

# Download directory with subdirectories
egs-tool download-directory <VM-ID> /remote/path/folder C:\local\folder --recursive

# Use --overwrite flag to replace existing files/directories
egs-tool upload-file <VM-ID> C:\local\file.txt /remote/path/file.txt --overwrite

Note: EGS has no FTP subsystem - use unison for file synchronization instead of scp.

Advanced: PowerShell Remoting Integration

If you have PowerShell 7 installed on both host and guest, EGS supports PowerShell remoting over SSH:

# Open PowerShell session
Enter-PSSession -HostName myvm

# Run PowerShell commands remotely
Invoke-Command -HostName myvm -ScriptBlock { Get-Process | Where-Object CPU -gt 100 }

This works on both Windows and Linux VMs (with PowerShell 7 installed).

How EGS Works Technically

EGS builds on proven Hyper-V technologies while solving their integration challenges:

The Technical Foundation

Like hvc ssh, EGS uses Hyper-V sockets for communication:

ProxyCommand hvc nc -t vsock <vmid> 5002

The key differences:

• Custom SSH server: EGS implements its own SSH server in the guest, avoiding OpenSSH compatibility issues
• Automatic configuration: The egs-tool generates SSH configuration files automatically
• Key management: SSH keys are exchanged via Hyper-V data exchange service, enabling passwordless authentication

Host-Side Configuration

EGS writes SSH configuration to %LOCALAPPDATA%\.eryph\ssh\config mapping hostnames to VM IDs and proxy commands:

Host myvm
    ProxyCommand hvc nc -t vsock 12345678-1234-1234-1234-123456789abc 5002
    User egs
    IdentityFile %LOCALAPPDATA%\.eryph\ssh\keys\myvm

Guest-Side Implementation

In the VM, EGS runs its own SSH daemon that:

• Listens on Hyper-V socket port 5002
• Uses exchanged keys for authentication
• Runs as the EGS service account (Windows) or root (Linux)
• Operates independently of any existing SSH server

Troubleshooting Common Issues

Common Issues

1. Status shows "unknown"

   • Guest services not installed or not running in VM
   • Check VM has Hyper-V integration services enabled

2. Authentication failed

   • Run egs-tool add-ssh-config <VM-ID> to set up authentication
   • Ensure you ran egs-tool initialize on the host

3. Connection refused

   • Guest service may not be running: check service status in VM
   • Hyper-V integration services may be disabled

4. File transfer failed

   • Check paths exist and have proper permissions
   • Use --overwrite flag if destination already exists
   • For directory transfers, ensure parent directories exist

Service Management

Windows VMs:

# Check service status
Get-Service eryph-guest-services

# Restart service
Restart-Service eryph-guest-services

Linux VMs:

# Check service status
sudo systemctl status eryph-guest-services

# Restart service
sudo systemctl restart eryph-guest-services

Summary

eryph Guest Services provides reliable SSH access to Hyper-V VMs without network configuration:

• Cross-platform: Works on both Windows and Linux VMs
• Standard SSH interface: Uses familiar SSH commands with generated aliases
• Built-in file transfers: Upload/download files and directories with support for recursive operations
• No configuration conflicts: Independent SSH server avoids OpenSSH issues
• Two deployment options: Integrate with eryph platform or use standalone with plain Hyper-V

EGS solves the limitations of PowerShell Direct (Windows-only), Copy-VMFile (no shell access), and hvc ssh (complex setup) with a unified solution that works consistently across operating systems.

For Source code and to report issues: https://github.com/eryph-org/guest-services.