VPN/docs/integration-plan.md

Based on my research, here's how the VPN server can extract MAC addresses:

MAC Address Extraction Methods

1. IV_HWADDR Environment Variable (Primary Method)

• Client Configuration: Add push-peer-info to client .ovpn config
• Environment Variable: IV_HWADDR contains the client's MAC address
• Format: Standard MAC format (e.g., 00:FF:01:02:03:04)

2. Client Configuration Requirements

In client.ovpn file

push-peer-info

3. Server Script Access

import os

def extract_mac_address(): # Primary method - IV_HWADDR from push-peer-info mac_address = os.environ.get('IV_HWADDR')

  if mac_address:
      return mac_address.strip()

  # Fallback - check other environment variables
  return None

Important Considerations

Client Compatibility Issues:

• OpenVPN2 clients: Generally send MAC addresses reliably
• OpenVPN3 clients: May send UUID strings instead of MAC addresses
• Older clients: May not provide MAC address at all

Alternative Approaches:

1. TAP Mode (Layer 2): - Use --dev tap instead of --dev tun - MAC addresses available through --learn-address script - More complex network setup required
2. Client Certificate Binding: - Embed MAC address in certificate Common Name or Subject Alt Name - More secure but requires certificate management per device
3. Custom Client Reporting: - Modify client to report MAC through custom authentication

Recommended Implementation

For your VPN access server, the most practical approach is:

1. Require push-peer-info in all client configurations
2. Extract from IV_HWADDR environment variable in client-connect script
3. Handle missing MAC addresses gracefully (log and potentially deny access)
4. Document client requirements for users/administrators

This method integrates seamlessly with your existing MySQL-based validation system in access/auth.py.