Question: Is vbox-api suitable for simple tasks like checking VirtualBox version?

[songyuc]

Hi @Zedeldi,

I'm a student learning about VirtualBox. I noticed that to check the VirtualBox version using vbox-api, we need to:

1. Start the VirtualBox web service (vboxwebsrv)
2. Set up a SOAP interface connection
3. Handle user authentication
4. Install multiple dependencies (as shown in pyproject.toml lines 17-23)

While the project seems powerful for complex VM management tasks (as shown in README.md examples from line 194 to line 254), I wonder if it's overkill for simple operations like version checking.

For comparison, we can simply use:

VBoxManage --version

I might feel that vbox-api is not suitable for my current focal task of checking the VirtualBox version.

To make sure of it, my questions are:

1. Is vbox-api primarily designed for complex VM management rather than simple queries?
2. Would it be helpful to add a note in the documentation suggesting the use of VBoxManage for basic operations?

I'm asking this to better understand the project's intended use cases and to help other beginners like me choose the right tool for their needs.

Thank you for creating this interesting project!

[Zedeldi]

Hi @songyuc,

As briefly mentioned in #10, vbox-api relies on the SOAP interface provided by vboxwebsrv, whereas other libraries use the COM interface.
This has several advantages, along with a few drawbacks:

• The SOAP web service can be bound/forwarded to an externally accessible location, allowing the management of a remote host.
• The SOAP web service communicates over HTTP/S, allowing easier integration with other libraries and for the web service to be forwarded or put behind a reverse proxy, etc.
• However, not all methods are supported over SOAP, as far as I am aware. For this reason, snapshot support (Add snapshot support #3) is limited.

This allows vbox-api to manage the VirtualBox instance (and its virtual machines) of another host.
For example, when using vbox-api-http, you can click the "Advanced settings" button to specify to which host the web server should connect, separating the vbox-api web server and the VirtualBox host. The connections between these components look something like this, where vbox-api-http and vboxwebsrv may be listening on the same or separate machine(s):

[Web browser] -> [vbox-api-http] -> [SOAPInterface] -> [vboxwebsrv] -> [VirtualBox COM]

All VirtualBox processes, whether the GUI or a virtual machine, communicate to VBoxSVC via COM. Please see the following snippet from the SDK documentation for more information:

VirtualBox employs a client-server design, meaning that whenever any part of VirtualBox is running – be it the Qt GUI, the VBoxManage command-line interface or any virtual machine –, a dedicated server process named VBoxSVC runs in the background. This allows multiple processes working with VirtualBox to cooperate without conflicts. These processes communicate to each other using inter-process communication facilities provided by the COM implementation of the host computer.

To answer your original question, in order to use any method of the SOAP interface, you must authenticate first.
However, you can set which method is used for authentication:

• System authentication: vboxwebsrv -A VBoxAuth (/usr/lib/virtualbox/VBoxAuth.so)
• No authentication: vboxwebsrv -A null

The latter will allow any username/password to be passed to IWebsessionManager.logon (or VBoxAPI.login).
Once authenticated, you can call VBoxAPI.get_version(), etc. to find the VirtualBox version of the host running the SOAP web service (vboxwebsrv).

If this is not appropriate and authentication is too cumbersome, then you'll need to use local tools, such as those provided by VirtualBox, e.g. VBoxManage --version, but this does not allow remote management of other hosts; you'd need to manage another host by a different means, e.g. SSH.

Hope this helps,
Zack :)

[Zedeldi]

To actually answer your original questions haha:

vbox-api is designed to make a generic Python interface, which internally uses the VirtualBox SOAP API.
It can be used for both complex and simple actions, as long as the SOAP API supports it.
When developing the web interface, I wanted to create something similar to VMware vSphere, for management of virtual machines via a web browser. It provides both a library which can be integrated into other Python projects, and a CLI/web interface to be used as standalone applications.

Regarding documentation, feel free to raise a PR adding this information to the README.md.
Unless we can create a local interface in vbox_api.interface inheriting BaseInterface, which provides most of the methods the SOAP interface supports using VirtualBox command-line tools (which I'm not sure would be either fun or clean), I think these tools would be outside of the scope of this project, but it may be worth mentioning this.

Please let me know if you have any other questions.

Many thanks,
Zack

[songyuc]

Hi,
I’m a student interested in learning about the "vbox-api" project. However, I’m currently unfamiliar with the concepts of "VirtualBox Main API" and "SOAP," and I feel a bit overwhelmed.

I’d like to ask if you could provide a simple code example demonstrating how to use "vbox-api" to check the VirtualBox version. This would help me better understand how the project works and how to use it.

Thank you so much for your time and effort in maintaining this project!

Best regards,
Eric

[Zedeldi]

Hi Eric,

No worries! Assuming vboxwebsrv is listening on localhost:18083 (default), here's some example code for how you'd create an interface, connect, login, then get the version:

from vbox_api import SOAPInterface, VBoxAPI

interface = SOAPInterface(host="localhost", port=18083)  # create SOAP client
interface.connect()  # connect and bind methods to interface instance
api = VBoxAPI(interface)  # create VirtualBox interface using SOAP client
api.login(username, password)  # get session handle - https://www.virtualbox.org/sdkref/interface_i_websession_manager.html

api.get_version()  # session handle is passed implicitly
api.get_api_version()

You can see this in action in the CLI and web interface: vbox_api.cli.__main__.main and vbox_api.http.session.SessionManager.login respectively.

Every object in the VirtualBox API is referenced by a handle. After logging in with api.login (which internally uses IWebsessionManager), a handle to the IVirtualBox instance is returned. When calling any API method, the relevant handle needs to be passed. This happens automatically with vbox-api, and users shouldn't need to worry about it, but it's worth knowing.

Hope this helps,
Zack