![\"Mascote](\"\/wp-content\/uploads\/2026\/09\/virtualbox-api-soap-sessoes-v1.webp\")
<\/p>\n<\/p>\n
The VirtualBox API allows integrating the hypervisor with inventories, automation tools, and custom dashboards. Before writing code, it's worth understanding the role of the SOAP service, how objects are identified, and why authentication, sessions, and security are part of the integration.<\/p>\n
This is part 1<\/strong>: the fundamentals of the API, with a focus on remote access through the web service. In part 2, we implemented a client in Go to list virtual machines<\/a>.<\/p>\n The The service The WSDL describes operations, parameters, namespaces, and responses of the web service. This contract guides the client's implementation; method and field names should not be inferred from an imagined REST API.<\/p>\n The operations and their parameters were verified against the WSDL included in the official SDK 7.2.0<\/a>, used as documentary reference for the line 7.2. This is not a recommendation to install an old patch: use a maintained version of VirtualBox and check the SDK corresponding to your environment.<\/p>\n You need VirtualBox with On the lab host, run as the user responsible for the environment, not as root. If the service is not yet active, a foreground start bound only to loopback is:<\/p>\n Do not disable authentication to make the example work. The username and password used in the SOAP login must match the authentication mechanism configured on the service, which is not necessarily identical across all installations.<\/p>\n The web service uses HTTP without encryption by default and usually binds to localhost. For access between machines, use TLS configured properly or a protected tunnel; do not publish the port directly on the internet. Oracle also recommends running the service as a regular user. Security guide<\/a>.<\/p>\n A lab option is to open this tunnel on the computer where the client will run:<\/p>\n Replace user and host. The client will keep using A SOAP reference is an object identifier used by the service during the session; it is not necessarily the VM's UUID. A read-only inventory flow is:<\/p>\n Do not persist SOAP references as if they were permanent IDs. To relate data in an inventory, use the returned UUID. For the next run, open a new session and obtain valid references again.<\/p>\n This is the next level of integration, not just swapping the method name. Write operations must respect the states, locks, machine sessions, and progress tracking defined by the API. The web service login and a session used to lock a machine should not be treated as the same concept.<\/p>\n My recommendation is to implement each operation separately, with authorization, confirmation when destructive, testing, and reconciliation after failure. An account capable of querying may also have other powers on the server; the fact that a client only queries does not reduce the privileges of the credential.<\/p>\n For a dashboard with Echo and Vue, keep this adapter separate from the HTTP handlers. Do not let the browser freely choose the endpoint, SOAP method, and arguments. Define explicit services, such as listing machines, and control destinations and permissions on the backend.<\/p>\n Start with a small operation: authenticate, get the machines, query their attributes, and end the session. Validate the contract, handle SOAP failures, and avoid logging credentials. Only afterward, add commands that change the state of the VMs.<\/p>\n At part 2: VirtualBox API in Go<\/a>, you will find the complete client files, JSON output, timeouts, and automated tests. To learn about a dashboard that uses this integration, also see the article about phpVirtualBox<\/a>.<\/p>","protected":false},"excerpt":{"rendered":" Understand the VirtualBox web service: WSDL contract, authentication, object references, sessions, and security before implementing a client.<\/p>","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[45,2,120],"tags":[31],"class_list":["post-1620","post","type-post","status-publish","format-standard","hentry","category-desenv","category-linux","category-servidores","tag-golang"],"_links":{"self":[{"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/posts\/1620","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/comments?post=1620"}],"version-history":[{"count":2,"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/posts\/1620\/revisions"}],"predecessor-version":[{"id":1624,"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/posts\/1620\/revisions\/1624"}],"wp:attachment":[{"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/media?parent=1620"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/categories?post=1620"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/tags?post=1620"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}API, VBoxManage, and web dashboard are not the same thing<\/h2>\n
VBoxManage<\/code> offers command-line administration. The web service exposes VirtualBox interfaces through SOAP, enabling HTTP calls with structured XML. A dashboard like the phpVirtualBox<\/a> is above this integration.<\/p>\nvboxwebsrv<\/code> receives SOAP calls. It should not be confused with a REST API that receives JSON. An application can offer REST to its own consumers and translate those requests into SOAP calls on the backend.<\/p>\nCliente \u2192 SOAP\/HTTP \u2192 vboxwebsrv \u2192 API do VirtualBox \u2192 VMs\n \u2193\nSa\u00edda definida pela aplica\u00e7\u00e3o<\/code><\/pre>\nThe SDK and the WSDL contract<\/h2>\n
Preparing the service with restricted access<\/h2>\n
vboxwebsrv<\/code> available on the host and the service authentication configured. The service executable belongs to the VirtualBox package; downloading the SDK alone does not install the server. The official SDK reference<\/a> describes its options and authentication.<\/p>\nvboxwebsrv --host 127.0.0.1 --port 18083<\/code><\/pre>\nssh -N -L 18083:127.0.0.1:18083 usuario@host-virtualbox<\/code><\/pre>\nhttp:\/\/127.0.0.1:18083\/<\/code>, but the transport between computers will stay inside SSH. If the local port is already in use, pick another one and adjust VBOX_URL<\/code>.<\/p>\nUnderstanding references, UUIDs, and sessions<\/h2>\n
\n\n
\n \nOperation<\/th>\n Client usage<\/th>\n<\/tr>\n<\/thead>\n \n IWebsessionManager_logon<\/code><\/td>\nAuthenticate and obtain the root reference.<\/td>\n<\/tr>\n \n IVirtualBox_getMachines<\/code><\/td>\nQuery the machine references.<\/td>\n<\/tr>\n \n IMachine_getId<\/code><\/td>\nGet the UUID.<\/td>\n<\/tr>\n \n IMachine_getName<\/code><\/td>\nGet the name.<\/td>\n<\/tr>\n \n IMachine_getState<\/code><\/td>\nGet the state.<\/td>\n<\/tr>\n \n IWebsessionManager_logoff<\/code><\/td>\nEnd the session.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n And what about starting VMs, creating snapshots, or changing settings?<\/h2>\n
From theory to a testable integration<\/h2>\n