Hypervisors - Nexus Access Vault

Overview

Nexus Access Vault provides centralized management for on-premises hypervisors and private cloud platforms. Connect to VMware, Proxmox, Hyper-V, KVM, and other virtualization platforms to manage VMs, hosts, and resources.

Supported Hypervisors

VMware ESXi/vSphere

Enterprise virtualization platform

Proxmox VE

Open-source virtualization management

Microsoft Hyper-V

Windows Server virtualization

KVM/QEMU

Kernel-based virtual machine

Citrix XenServer

Enterprise virtualization solution

oVirt

Open-source virtualization management

Database Schema

Hypervisor configurations are stored in the hypervisors table:

CREATE TABLE hypervisors (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  organization_id UUID NOT NULL REFERENCES organizations(id),
  name TEXT NOT NULL,
  hypervisor_type TEXT NOT NULL,
  api_endpoint TEXT NOT NULL,
  credentials JSONB NOT NULL, -- encrypted
  metadata JSONB,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

Adding Hypervisors

Via Portal UI

Navigate to the Hypervisors page (src/pages/Hypervisors.tsx) and click “Add Hypervisor”:

Enter a descriptive name (e.g., “Proxmox Datacenter 1”)
Select hypervisor type from dropdown
Enter API endpoint URL
Optionally specify physical location
Provide authentication credentials
Click “Add Hypervisor”

Programmatically

const { error } = await supabase
  .from('hypervisors')
  .insert({
    organization_id: profile.organization_id,
    name: 'Proxmox Datacenter 1',
    hypervisor_type: 'proxmox',
    api_endpoint: 'https://proxmox.local:8006',
    metadata: { location: 'Datacenter Principal, Rack A' },
    credentials: {
      username: 'root@pam',
      password: 'secure-password',
    },
  });

Hypervisor-Specific Configuration

VMware ESXi / vSphere

API Endpoint Format:

https://vcenter.example.com/sdk

Required Credentials:

credentials: {
  username: '[email protected]',
  password: 'secure-password',
  domain: 'vsphere.local' // optional
}

Configuration Steps:

Enable API Access

Ensure the vSphere API is enabled (default on vCenter)

Create Service Account

Create a dedicated user account with read-only or admin permissions

Note API Endpoint

Use the vCenter hostname/IP with /sdk path

Test Connection

Verify connectivity using PowerCLI or API client

Proxmox VE

API Endpoint Format:

https://proxmox.local:8006

Required Credentials:

credentials: {
  username: 'root@pam',
  password: 'secure-password',
  // OR use API token
  token_id: 'root@pam!mytoken',
  token_secret: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
}

Configuration Steps:

Access Proxmox UI

Create API Token

Navigate to Datacenter → Permissions → API Tokens

Generate Token

Create a new token with appropriate privileges

Add to Portal

Use token credentials in Nexus Access Vault

API Token Example:

curl -k -d "username=root@pam&password=yourpassword" \
  https://proxmox.local:8006/api2/json/access/ticket

Microsoft Hyper-V

API Endpoint Format:

https://hyperv-host.local:5986

Required Credentials:

credentials: {
  username: 'DOMAIN\\Administrator',
  password: 'secure-password'
}

Configuration Steps:

Enable WinRM

Enable Windows Remote Management on the Hyper-V host

Configure HTTPS Listener

Set up WinRM HTTPS listener on port 5986

Configure Firewall

Allow port 5986 through Windows Firewall

Test Connection

Verify using PowerShell:

Test-WSMan -ComputerName hyperv-host.local -UseSSL

KVM/QEMU (libvirt)

API Endpoint Format:

qemu+ssh://[email protected]/system

Required Credentials:

credentials: {
  username: 'root',
  password: 'secure-password',
  // OR use SSH key
  ssh_key: '-----BEGIN OPENSSH PRIVATE KEY-----\n...'
}

Configuration Steps:

Install libvirt

Ensure libvirtd is running:

systemctl status libvirtd

Configure SSH Access

Set up SSH key authentication for remote access

Test Connection

Verify using virsh:

virsh -c qemu+ssh://[email protected]/system list

Citrix XenServer

API Endpoint Format:

https://xenserver.local

Required Credentials:

credentials: {
  username: 'root',
  password: 'secure-password'
}

Portal UI Component

The Hypervisors page (src/pages/Hypervisors.tsx) provides a management interface:

Features

List View: Display all configured hypervisors
Add Dialog: Modal form to add new hypervisors
Hypervisor Cards: Visual cards showing hypervisor details
Delete Action: Remove hypervisor configurations
Location Metadata: Track physical location of hosts

Component Structure

interface Hypervisor {
  id: string;
  name: string;
  hypervisor_type: string;
  api_endpoint: string;
  metadata: any;
  created_at: string;
}

const loadHypervisors = async () => {
  const { data, error } = await supabase
    .from('hypervisors')
    .select('id, name, hypervisor_type, api_endpoint, metadata, created_at')
    .eq('organization_id', profile.organization_id)
    .order('created_at', { ascending: false });
};

Metadata Fields

Store additional information in the metadata JSONB column:

metadata: {
  location: 'Datacenter Principal, Rack A',
  ip_address: '192.168.1.100',
  total_memory: '512GB',
  total_cpu: '64 cores',
  version: '7.2',
  cluster_name: 'Production Cluster',
  tags: ['production', 'critical']
}

Security Best Practices

Credential Protection: Hypervisor credentials provide full access to your virtual infrastructure. Store them encrypted and restrict access to authorized personnel only.

Recommendations

Use Dedicated Accounts: Create service accounts specifically for API access
Least Privilege: Grant minimal permissions required (prefer read-only)
Network Isolation: Access hypervisor APIs only through secure networks (VPN)
Certificate Validation: Verify SSL certificates for API endpoints
Credential Rotation: Regularly rotate passwords and API tokens
Audit Logging: Monitor API access logs on hypervisor platforms
IP Restrictions: Limit API access by source IP when supported
Two-Factor Authentication: Enable 2FA on hypervisor accounts

SSL/TLS Configuration

Many hypervisors use self-signed certificates. Handle these appropriately:

Accept Self-Signed Certificates (Development Only)

// NOT recommended for production
const agent = new https.Agent({
  rejectUnauthorized: false
});

Trust Custom CA (Production)

import fs from 'fs';

const ca = fs.readFileSync('/path/to/ca-cert.pem');
const agent = new https.Agent({ ca });

API Integration Examples

Proxmox VE - List VMs

import axios from 'axios';

const { data: hypervisor } = await supabase
  .from('hypervisors')
  .select('api_endpoint, credentials')
  .eq('id', hypervisorId)
  .single();

// Authenticate
const authResponse = await axios.post(
  `${hypervisor.api_endpoint}/api2/json/access/ticket`,
  {
    username: hypervisor.credentials.username,
    password: hypervisor.credentials.password,
  },
  { httpsAgent: new https.Agent({ rejectUnauthorized: false }) }
);

const ticket = authResponse.data.data.ticket;
const csrfToken = authResponse.data.data.CSRFPreventionToken;

// List VMs
const vmsResponse = await axios.get(
  `${hypervisor.api_endpoint}/api2/json/cluster/resources?type=vm`,
  {
    headers: {
      Cookie: `PVEAuthCookie=${ticket}`,
      CSRFPreventionToken: csrfToken,
    },
  }
);

console.log('VMs:', vmsResponse.data.data);

VMware vSphere - List VMs

import { VimClient } from 'vsphere-connect';

const client = new VimClient({
  host: 'vcenter.example.com',
  username: hypervisor.credentials.username,
  password: hypervisor.credentials.password,
  ignoreSSL: false,
});

await client.login();
const vms = await client.listVirtualMachines();
console.log('VMs:', vms);
await client.logout();

Hyper-V - List VMs (PowerShell via WinRM)

import { Client } from 'node-winrm';

const client = new Client({
  host: 'hyperv-host.local',
  port: 5986,
  username: hypervisor.credentials.username,
  password: hypervisor.credentials.password,
});

const result = await client.runPowerShell('Get-VM');
console.log('VMs:', result.stdout);

Monitoring and Health Checks

Connection Health

Implement periodic health checks:

const checkHypervisorHealth = async (hypervisor: Hypervisor) => {
  try {
    switch (hypervisor.hypervisor_type) {
      case 'proxmox':
        // Test Proxmox API
        await axios.get(`${hypervisor.api_endpoint}/api2/json/version`);
        break;
      case 'vmware':
        // Test vSphere API
        // Implement vCenter connection test
        break;
      case 'hyperv':
        // Test WinRM connection
        // Implement WinRM test
        break;
    }
    return { status: 'healthy', lastCheck: new Date() };
  } catch (error) {
    return { status: 'error', error: error.message };
  }
};

Resource Monitoring

Track hypervisor resource utilization:

const getResourceStats = async (hypervisor: Hypervisor) => {
  // Fetch CPU, memory, storage usage from hypervisor API
  return {
    cpu_usage: 45.2,
    memory_usage: 78.5,
    storage_usage: 62.1,
    vm_count: 24,
    running_vms: 18,
  };
};

Troubleshooting

Connection Refused

Problem: Cannot connect to hypervisor API Solutions:

Verify API endpoint URL is correct
Check hypervisor firewall allows incoming connections

Test connectivity:

telnet proxmox.local 8006
curl -k https://proxmox.local:8006/api2/json/version

SSL Certificate Errors

Problem: “SSL certificate problem: self signed certificate” Solutions:

Add CA certificate to trusted store (production)
Use rejectUnauthorized: false for testing only

Verify certificate chain:

openssl s_client -connect proxmox.local:8006

Authentication Failed

Problem: Invalid credentials or permission denied Solutions:

Verify username and password are correct
Check account has necessary permissions
For Proxmox, verify realm (e.g., @pam, @pve)
For VMware, check domain format

API Rate Limiting

Problem: Too many requests to hypervisor API Solutions:

Implement request throttling
Cache API responses when appropriate
Use websockets for real-time updates instead of polling

Network Access via VPN

For security, access on-premises hypervisors through a VPN connection like Tailscale or NetBird. Never expose hypervisor APIs directly to the internet.

Example network architecture:

[Nexus Portal] → [Tailscale VPN] → [On-Prem Network] → [Hypervisors]

See:

Cloud Providers - Public cloud infrastructure
Tailscale Integration - Secure hypervisor access
NetBird Integration - VPN connectivity

Overview

Getting Started

Authentication & SSO

Core Features

Network & Infrastructure

Administration

Deployment

​Overview

​Supported Hypervisors

VMware ESXi/vSphere

Proxmox VE

Microsoft Hyper-V

KVM/QEMU

Citrix XenServer

oVirt

​Database Schema

​Adding Hypervisors

​Via Portal UI

​Programmatically

​Hypervisor-Specific Configuration

​VMware ESXi / vSphere

​Proxmox VE

​Microsoft Hyper-V

​KVM/QEMU (libvirt)

​Citrix XenServer

​Portal UI Component

​Features

​Component Structure

​Metadata Fields

​Security Best Practices

​Recommendations

​SSL/TLS Configuration

​Accept Self-Signed Certificates (Development Only)

​Trust Custom CA (Production)

​API Integration Examples

​Proxmox VE - List VMs

​VMware vSphere - List VMs

​Hyper-V - List VMs (PowerShell via WinRM)

​Monitoring and Health Checks

​Connection Health

​Resource Monitoring

​Troubleshooting

​Connection Refused

​SSL Certificate Errors

​Authentication Failed

​API Rate Limiting

​Network Access via VPN

​Related Resources

Build docs developers (and LLMs) love

Overview

Supported Hypervisors

Database Schema

Adding Hypervisors

Via Portal UI

Programmatically

Hypervisor-Specific Configuration

VMware ESXi / vSphere

Proxmox VE

Microsoft Hyper-V

KVM/QEMU (libvirt)

Citrix XenServer

Portal UI Component

Features

Component Structure

Metadata Fields

Security Best Practices

Recommendations

SSL/TLS Configuration

Accept Self-Signed Certificates (Development Only)

Trust Custom CA (Production)

API Integration Examples

Proxmox VE - List VMs

VMware vSphere - List VMs

Hyper-V - List VMs (PowerShell via WinRM)

Monitoring and Health Checks

Connection Health

Resource Monitoring

Troubleshooting

Connection Refused

SSL Certificate Errors

Authentication Failed

API Rate Limiting

Network Access via VPN

Related Resources