{"id":1620,"date":"2026-09-14T10:20:55","date_gmt":"2026-09-14T13:20:55","guid":{"rendered":"https:\/\/www.linuxpro.com.br\/?p=1620"},"modified":"2026-10-07T08:37:50","modified_gmt":"2026-10-07T11:37:50","slug":"api-do-virtualbox-parte-1-soap-sessoes-e-seguranca","status":"publish","type":"post","link":"https:\/\/www.linuxpro.com.br\/es\/2026\/09\/api-do-virtualbox-parte-1-soap-sessoes-e-seguranca\/","title":{"rendered":"API de VirtualBox \u2014 parte 1: SOAP, sesiones y seguridad"},"content":{"rendered":"

\"Mascote<\/p>\n

La API de VirtualBox permite integrar el hipervisor en inventarios, herramientas de automatizaci\u00f3n y paneles propios. Antes de escribir c\u00f3digo, conviene comprender el papel del servicio SOAP, c\u00f3mo se identifican los objetos y por qu\u00e9 la autenticaci\u00f3n, las sesiones y la seguridad forman parte de la integraci\u00f3n.<\/p>\n

Esta es la parte 1<\/strong>: los fundamentos de la API, con foco en el acceso remoto mediante el servicio web. En la parte 2, implementamos un cliente en Go para listar m\u00e1quinas virtuales<\/a>.<\/p>\n

API, VBoxManage y panel web no son lo mismo<\/h2>\n

O VBoxManage<\/code> ofrece administraci\u00f3n mediante l\u00ednea de comandos. El servicio web expone interfaces de VirtualBox mediante SOAP, permitiendo llamadas HTTP con XML estructurado. Un panel como el phpVirtualBox<\/a> se sit\u00faa por encima de esa integraci\u00f3n.<\/p>\n

El servicio vboxwebsrv<\/code> recibe llamadas SOAP. No debe confundirse con una API REST que recibe JSON. Una aplicaci\u00f3n puede ofrecer REST a sus propios consumidores y traducir esas solicitudes en llamadas SOAP en el backend.<\/p>\n

\"Arquitetura<\/a>
Diagrama ampliado: transporte protegido, contexto del host y tres conceptos que no deben confundirse. Haz clic para abrir en resoluci\u00f3n completa. El dibujo muestra la opci\u00f3n con t\u00fanel SSH; TLS es una alternativa de transporte.<\/figcaption><\/figure>\n

Tres responsabilidades: transporte, identidad y autorizaci\u00f3n<\/h2>\n\n\n\n\n\n\n\n
Pregunta<\/th>\nCapa responsable<\/th>\nError a evitar<\/th>\n<\/tr>\n<\/thead>\n
\u00bfEstoy hablando con el servidor correcto sin exponer el tr\u00e1fico?<\/td>\nSSH o TLS con validaci\u00f3n de identidad del host.<\/td>\nDeshabilitar la verificaci\u00f3n de host\/certificado para ocultar un problema.<\/td>\n<\/tr>\n
\u00bfQui\u00e9n est\u00e1 llamando al servicio?<\/td>\nAutenticaci\u00f3n del servicio web.<\/td>\nSuponer que el t\u00fanel SSH sustituye al inicio de sesi\u00f3n SOAP.<\/td>\n<\/tr>\n
\u00bfQu\u00e9 m\u00e1quinas y acciones puede acceder esta persona?<\/td>\nPol\u00edtica del entorno y de la aplicaci\u00f3n que expone el acceso.<\/td>\nOtorgar a todos los usuarios del panel los poderes de la cuenta de servicio.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Estas capas se complementan. HTTPS no decide si alguien puede borrar un disco; la autenticaci\u00f3n no cifra el tr\u00e1fico; un bot\u00f3n oculto no impide una llamada indebida al backend. En el panel, defina operaciones expl\u00edcitas y autorice cada una antes de alcanzar el adaptador SOAP.<\/p>\n

El SDK y el contrato WSDL<\/h2>\n

Documentaci\u00f3n oficial de la API:<\/strong> consulte la VirtualBox Main API \u2014 referencia oficial<\/a>. Re\u00fane las interfaces, m\u00e9todos, atributos y tipos utilizados en la integraci\u00f3n. Para implementar el cliente SOAP, consulte tambi\u00e9n el WSDL y la referencia del SDK correspondiente a la versi\u00f3n de su entorno; la documentaci\u00f3n en l\u00ednea puede corresponder a una versi\u00f3n diferente.<\/p>\n

El WSDL describe operaciones, par\u00e1metros, espacios de nombres y respuestas del servicio web. Es ese contrato el que gu\u00eda la implementaci\u00f3n del cliente; los nombres de m\u00e9todos y campos no deben deducirse de una API REST imaginada.<\/p>\n

Las operaciones y sus par\u00e1metros se han revisado en el WSDL incluido en el SDK oficial 7.2.0<\/a>, utilizado como referencia documental de la l\u00ednea 7.2. Esto no es una recomendaci\u00f3n para instalar un parche antiguo: usa una versi\u00f3n mantenida de VirtualBox y consulta el SDK correspondiente a tu entorno.<\/p>\n

Preparar el servicio con acceso restringido<\/h2>\n

Necesitas VirtualBox con vboxwebsrv<\/code> disponible en el host y autenticaci\u00f3n del servicio configurada. El ejecutable del servicio pertenece al paquete de VirtualBox; descargar solo el SDK no instala el servidor. La referencia oficial del SDK<\/a> describe sus opciones y autenticaci\u00f3n.<\/p>\n

En el host de laboratorio, ejec\u00fatalo como el usuario responsable del entorno, no como root. Si el servicio a\u00fan no est\u00e1 activo, un inicio en primer plano y solo en loopback es:<\/p>\n

vboxwebsrv --host 127.0.0.1 --port 18083<\/code><\/pre>\n
No deshabilites la autenticaci\u00f3n para que el ejemplo funcione. El usuario y la contrase\u00f1a usados en el inicio de sesi\u00f3n SOAP deben coincidir con el mecanismo de autenticaci\u00f3n configurado en el servicio, que no es necesariamente id\u00e9ntico en todas las instalaciones.<\/p>\n
El servicio web utiliza HTTP sin cifrado por defecto y normalmente se vincula al localhost. Para acceso entre m\u00e1quinas, utiliza TLS configurado correctamente o un t\u00fanel protegido; no publiques el puerto directamente en internet. Oracle tambi\u00e9n recomienda ejecutar el servicio como un usuario normal. Gu\u00eda de seguridad<\/a>.<\/p>\n
Una opci\u00f3n de laboratorio es abrir este t\u00fanel en el equipo en el que se ejecutar\u00e1 el cliente:<\/p>\n
ssh -N -o ExitOnForwardFailure=yes \\\n  -L 127.0.0.1:18083:127.0.0.1:18083 usuario@host-virtualbox<\/code><\/pre>\n
Sustituye usuario y host. El cliente seguir\u00e1 usando http:\/\/127.0.0.1:18083\/<\/code>, pero el transporte entre equipos permanecer\u00e1 dentro de SSH. Si el puerto local ya est\u00e1 ocupado, elige otro y aj\u00fastalo VBOX_URL<\/code>.<\/p>\n
Entiende las dos direcciones de loopback<\/h3>\n
En el comando, el primero 127.0.0.1:18083<\/code> limita la escucha al equipo del cliente. El segundo es el destino visto por el servidor SSH, normalmente el propio host de VirtualBox. El reenv\u00edo no debe escuchar en 0.0.0.0<\/code> ni depender de una configuraci\u00f3n global permisiva de SSH.<\/p>\n
ExitOnForwardFailure=yes<\/code> hace que SSH finalice si no logra establecer el reenv\u00edo, por ejemplo cuando el puerto local est\u00e1 ocupado. Esto no comprueba<\/strong> que el servicio en el destino est\u00e9 funcionando: fallos posteriores al conectar en vboxwebsrv<\/code> a\u00fan deben diagnosticarse. Verifique la identidad SSH del servidor por un canal fiable antes de aceptar su clave. Referencia de OpenSSH<\/a>.<\/p>\n
En Linux, compruebe la escucha en el host del servicio:<\/p>\n
ss -ltn 'sport = :18083'<\/code><\/pre>\n
Para el comando de inicio mostrado, espere 127.0.0.1:18083<\/code>, no una direcci\u00f3n que escuche en todas las interfaces. Un socket abierto es solo evidencia de transporte: no valida credenciales ni llamadas SOAP. Si ya existe una instalaci\u00f3n en funcionamiento, inspecci\u00f3nela antes de iniciar otro proceso en el mismo puerto.<\/p>\n
La cuenta del servicio define el contexto del inventario<\/h3>\n
No inicie el proceso con sudo<\/code> solo porque una lista vino vac\u00eda. El entorno de usuario del servicio determina qu\u00e9 m\u00e1quinas virtuales est\u00e1n registradas y disponibles. Confirme la cuenta responsable, sus permisos y la configuraci\u00f3n de VirtualBox; autenticarse en SOAP no equivale a cambiar libremente el usuario del proceso en el host.<\/p>\n
Use una cuenta y m\u00e1quinas de laboratorio para homologaci\u00f3n. No trate loopback como una barrera suficiente contra todos los procesos e invitados del host; mantenga la autenticaci\u00f3n y las restricciones del entorno. El acceso local no significa que todos los posibles llamantes sean de confianza.<\/p>\n
Entender referencias, UUIDs y sesiones<\/h2>\n
Una referencia SOAP es un identificador de objeto utilizado por el servicio durante la sesi\u00f3n; no es necesariamente el UUID de la VM. Un flujo de inventario de solo lectura es:<\/p>\n\n\n\n\n\n\n\n\n\n\n
Operaci\u00f3n<\/th>\nUso en el cliente<\/th>\n<\/tr>\n<\/thead>\n
IWebsessionManager_logon<\/code><\/td>\nAutenticar y obtener la referencia ra\u00edz.<\/td>\n<\/tr>\n
IVirtualBox_getMachines<\/code><\/td>\nConsultar las referencias de las m\u00e1quinas.<\/td>\n<\/tr>\n
IMachine_getId<\/code><\/td>\nObtener el UUID.<\/td>\n<\/tr>\n
IMachine_getName<\/code><\/td>\nObtener el nombre.<\/td>\n<\/tr>\n
IMachine_getState<\/code><\/td>\nObtener el estado.<\/td>\n<\/tr>\n
IWebsessionManager_logoff<\/code><\/td>\nCerrar la sesi\u00f3n.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
No persistas referencias SOAP como si fueran ID permanentes. Para relacionar datos en un inventario, utiliza el UUID devuelto. Para la pr\u00f3xima ejecuci\u00f3n, abre una nueva sesi\u00f3n y obt\u00e9n referencias v\u00e1lidas de nuevo.<\/p>\n
UUID, referencia gestionada y sesi\u00f3n de m\u00e1quina<\/h3>\n\n\n\n\n\n\n\n\n
Concepto<\/th>\nFunci\u00f3n<\/th>\nC\u00f3mo usar<\/th>\n<\/tr>\n<\/thead>\n
UUID de la m\u00e1quina virtual<\/td>\nIdentificar la m\u00e1quina en el inventario.<\/td>\n\u00daselo como clave, no como el nombre mostrado; no asuma identidad preservada al clonar\/recrear.<\/td>\n<\/tr>\n
Referencia SOAP<\/td>\nApuntar a un objeto remoto v\u00e1lido en el contexto del servicio.<\/td>\nNo lo env\u00ede al navegador, no lo use como secreto permanente ni lo reutilice entre inicios de sesi\u00f3n.<\/td>\n<\/tr>\n
Websession<\/td>\nContexto creado por el inicio de sesi\u00f3n SOAP.<\/td>\nCierre la sesi\u00f3n y gestione la expiraci\u00f3n, los fallos de red y la reconexi\u00f3n.<\/td>\n<\/tr>\n
ISession<\/code><\/td>\nParticipe en el control de acceso\/bloqueo de una m\u00e1quina.<\/td>\nSiga el ciclo exigido por la operaci\u00f3n; no lo confunda con la websession.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
La documentaci\u00f3n de IWebsessionManager<\/a> describe el inicio de sesi\u00f3n, la obtenci\u00f3n de un objeto de sesi\u00f3n y el cierre de sesi\u00f3n. El cierre de sesi\u00f3n elimina los recursos asociados a la websession. Por su parte, ISession<\/a> tiene reglas espec\u00edficas de bloqueo y liberaci\u00f3n: cuando la operaci\u00f3n adquiera un bloqueo que lo requiera unlockMachine<\/code>, debe liberarse expl\u00edcitamente. No use cerrar la websession como sustituto gen\u00e9rico de ese ciclo.<\/p>\n
La limpieza es un intento controlado, no una garant\u00eda de red<\/h3>\n
Registre la limpieza en cuanto reciba una referencia v\u00e1lida. Utilice un plazo corto independiente del contexto principal para que cancelar la recolecci\u00f3n no impida inmediatamente el cierre de sesi\u00f3n. Si el inicio de sesi\u00f3n ha sido aceptado pero su respuesta se pierde, es posible que el cliente ni siquiera conozca la referencia necesaria para limpiar; la expiraci\u00f3n de sesiones del servidor sigue siendo necesaria.<\/p>\n
El inventario tampoco es una fotograf\u00eda at\u00f3mica: el estado y la configuraci\u00f3n pueden cambiar entre llamadas. Una respuesta vac\u00eda, un fallo SOAP y una referencia caducada son resultados diferentes y deben aparecer de forma diferente en el cliente.<\/p>\n
\u00bfY para iniciar VMs, crear instant\u00e1neas o cambiar la configuraci\u00f3n?<\/h2>\n
Este es el siguiente nivel de integraci\u00f3n, no un simple cambio del nombre del m\u00e9todo. Las operaciones de escritura deben respetar estados, bloqueos, sesiones de m\u00e1quina y seguimiento de progreso definidos por la API. El inicio de sesi\u00f3n del servicio web y una sesi\u00f3n utilizada para bloquear una m\u00e1quina no deben tratarse como el mismo concepto.<\/p>\n
Mi recomendaci\u00f3n es implementar cada operaci\u00f3n por separado, con autorizaci\u00f3n, confirmaci\u00f3n cuando sea destructiva, pruebas y reconciliaci\u00f3n tras un fallo. Una cuenta capaz de consultar tambi\u00e9n puede tener otros poderes en el servidor; el hecho de que un cliente solo consulte no reduce los privilegios de la credencial.<\/p>\n
Para un panel con Echo y Vue, mantenga este adaptador separado de los handlers HTTP. No permita que el navegador elija libremente endpoint, m\u00e9todo SOAP y argumentos. Defina servicios expl\u00edcitos, como listar m\u00e1quinas, y controle destinos y permisos en el backend.<\/p>\n
Operaciones largas: sigue el resultado, no solo el HTTP<\/h2>\n
Una respuesta HTTP de \u00e9xito no prueba que una tarea larga haya terminado. Cuando la operaci\u00f3n devuelva IProgress<\/code>, realice un seguimiento de su finalizaci\u00f3n y del resultado documentado, incluida la informaci\u00f3n de error cuando proceda. No toda operaci\u00f3n devuelve este objeto: consulte el contrato del m\u00e9todo. Referencia de IProgress<\/a>.<\/p>\n
Si la conexi\u00f3n se cae despu\u00e9s del env\u00edo, el resultado puede ser desconocido. Consulte el estado real antes de reenviar: el tiempo de espera del cliente no cancela autom\u00e1ticamente la acci\u00f3n en el hipervisor. Diferencie en el panel \u201cfall\u00f3\u201d, \u201cen curso\u201d y \u201cresultado pendiente de confirmar\u201d. Esta es una de las razones para empezar por el inventario, no por operaciones destructivas.<\/p>\n
Diagn\u00f3stico por capa<\/h2>\n\n\n\n\n\n\n\n\n\n\n
S\u00edntoma<\/th>\nInvestigue primero<\/th>\nNo haga<\/th>\n<\/tr>\n<\/thead>\n
Conexi\u00f3n rechazada<\/td>\nProceso, direcci\u00f3n de escucha, puerto y t\u00fanel.<\/td>\nAbrir el servicio a toda la red como intento aleatorio.<\/td>\n<\/tr>\n
XML inesperado o p\u00e1gina HTML<\/td>\nURL e intermediarios; un inicio de sesi\u00f3n de proxy no es una respuesta SOAP.<\/td>\nTratar cualquier HTTP 200 como \u00e9xito de la operaci\u00f3n.<\/td>\n<\/tr>\n
Fallo en el inicio de sesi\u00f3n<\/td>\nMecanismo de autenticaci\u00f3n y credenciales del laboratorio.<\/td>\nDeshabilitar la autenticaci\u00f3n.<\/td>\n<\/tr>\n
Lista vac\u00eda<\/td>\nRegistro de las m\u00e1quinas virtuales en el contexto del usuario del servicio.<\/td>\nVolver a ejecutar como root sin entender el entorno.<\/td>\n<\/tr>\n
Referencia no v\u00e1lida<\/td>\nCaducidad, cierre de sesi\u00f3n anterior y reutilizaci\u00f3n entre sesiones.<\/td>\nPersistir la referencia e intentar usarla indefinidamente.<\/td>\n<\/tr>\n
Operaci\u00f3n sin resultado<\/td>\nEstado real, progreso y registros saneados.<\/td>\nRepetir la escritura autom\u00e1ticamente.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Checklist antes de conectar un panel o agente<\/h2>\n