Tornevall Networks

← Back to docs

VirtualBox Manager

Language: EN | EN | SV

VirtualBox Manager

VirtualBox Manager is the web GUI in Tools for managing VirtualBox hosts through the VirtualBox WebService SOAP API.

  • Tools connects to a configured vboxwebsrv endpoint over HTTP or HTTPS.
  • The saved host and port should point to the reverse proxy in front of vboxwebsrv.
  • The saved username and password are used as the VirtualBox WebService API credentials.
  • Those credentials come from the VirtualBox host setup itself (for example the vboxapi user created by your install-vbox-proxy.sh-style host installer). They are not the same thing as your normal Tools web login.

Route: /admin/virtualbox

Access

  • Requires login
  • Requires permission: virtualbox.manage

What you can do

  • Register one or many VirtualBox WebService endpoints (host, port, API username, API password)
  • Keep servers grouped in dedicated sections
  • Expand each server to see all VMs in a compact first view
  • Start, stop, restart, and delete VMs
  • Run most operations via AJAX (no full-page postback for normal operations)
  • Apply core VM settings from the same panel:
    • Memory (MB)
    • CPU count
    • VRAM (MB)
    • Primary boot device
  • Create new VMs from the same server card with setup defaults:
    • Network mode: bridged (default)
    • Memory: 1024 MB (default)
    • Disk: 25 GB (default)
    • Optional install ISO attachment

How to add a server

  1. Open /admin/virtualbox
  2. Fill in:
    • Label
    • Host (for example http://10.1.1.56)
    • Port (default 8443 for the reverse-proxied vboxwebsrv endpoint)
    • API username from the VirtualBox host (for example vboxapi)
    • API password for that same VirtualBox WebService user
  3. Save
  4. Click Test connection

If your credentials and host are valid, the server card loads VM inventory directly.

Endpoint requirements

  • A reverse proxy or direct listener must expose the target vboxwebsrv endpoint.
  • The reference install-vbox-proxy.sh setup exposes plain http://HOST:8443 by default. Use https:// only if you added TLS termination yourself in front of the proxy.
  • If the host field omits http:// or https://, Tools assumes http://.
  • The saved port is appended to the host unless the host field already contains an explicit port.
  • The target PHP runtime must have the SOAP extension enabled, because Tools now talks to VirtualBox through SOAP instead of shelling out to VBoxManage.
  • Tools now inspects the actual WSDL method list first and prefers VirtualBox-style operations such as IWebsessionManager_logon, IWebsessionManager_logoff, and IWebsessionManager_getSessionObject before falling back to generic guesses.
  • If the generated VirtualBox WSDL itself is reachable but PHP SOAP fails with a Parsing WSDL / Couldn't bind to service style error, Tools now retries the same endpoint through non-WSDL SOAP client candidates automatically instead of failing immediately.
  • If the WSDL client reaches the server but login fails with a namespace/method fault such as Method 'ns1:logon' not implemented: method name or namespace not recognized, Tools now retries the same login through both known VirtualBox SOAP URIs:
    • http://www.virtualbox.org/
    • http://www.virtualbox.org/Service
  • When login still fails, the admin diagnostics now keep the effective endpoint, WSDL URL, selected SOAP mode, selected SOAP URI, available WSDL functions, and the attempted login sequence visible in the raw debug payload.

New VM setup flow

Each server segment now includes a Create new VM section.

Required:

  • VM name

Optional (pre-filled defaults):

  • OS type (Other_64 by default)
  • Memory (1024)
  • Disk size in GB (25)
  • CPU count (1)
  • Network mode (bridged default)
  • Bridge adapter (Auto uses first detected bridged adapter)
  • Install ISO path (optional)

This setup flow intentionally focuses on practical VM provisioning without requiring unattended/autoinstall.

Installable ISO support

  • Tools now checks server-registered DVD media via VirtualBox and exposes those paths in the VM setup datalist.
  • ISO attach remains optional; if omitted, VM is created as a disk-only setup ready for later install media attachment.
  • If ISO inventory lookup fails for a server, the create form still works with manual ISO path input.

VM operation notes

  • Start: starts VM headless
  • Stop: sends ACPI power button signal
  • Restart: sends reset
  • Delete: unregisters VM and removes attached files/disks (unregistervm --delete)

Use delete with care.

Security notes

  • Server passwords are stored encrypted in Tools database.
  • VM actions are executed server-side by Tools through the VirtualBox WebService SOAP API.
  • Only users with virtualbox.manage can access this panel.

Current scope

This release focuses on a practical MVP with professional grouped UI and operational control.

Planned later enhancements may include:

  • Fine-grained delegation per server/VM
  • Richer storage/network editor sections
  • Better live state refresh and longer-running task handling