Referencia de CLI y API
La CLI, la API JSON y el servidor MCP de hv exponen operaciones con los mismos conceptos que la consola. Sirven para administración repetible e integración. Antes de modificar recursos, identifique Pool y Proyecto, obtenga los permisos de cuenta necesarios y establezca una conexión de confianza con la instalación correcta.
Utilizar la CLI
El Host instalado incluye hv. Para un equipo de trabajo, obtenga una CLI de la misma versión de quien distribuye hv. Más adelante se reúnen los comandos utilizados en este manual; hv --help y la ayuda de cada subcomando describen el binario instalado.
Los comandos locales utilizan la base configurada y, por defecto, la identidad privilegiada System. Seleccione producción explícitamente:
HV_ENV=prod hv pool list --config /etc/hv/prod.toml
HV_ENV=prod hv vm list --config /etc/hv/prod.toml --pool POOL --jsonLos comandos remotos utilizan la API y la cuenta del token. Un archivo privado preparado por el administrador puede proporcionar el token sin incluirlo en argumentos:
hv vm show VM --pool POOL --server https://hv.example.com:8443 --token-stdin < /secure/hv-api-tokenTambién se admiten HV_SERVER y HV_TOKEN. No use la entrada estándar para el token con un comando que ya la consume para contraseñas. --ca-file añade una CA privada de confianza; no desactive la verificación para resolver una discrepancia de certificado sin identificar.
La mayoría de selectores aceptan referencia, UUID o nombre inequívoco. Use --pool si hay varios Pools. hv project use NAME selecciona el Proyecto predeterminado; --project explícito evita ambigüedades en automatización. Los roles de flota pueden seleccionar otro Silo con --silo.
Los códigos de salida son 0 para éxito, 1 para fallo de operación, 2 para uso o entrada rechazada, 3 para acceso denegado y 4 para objeto no encontrado. El éxito puede significar que se encoló una tarea; compruebe su finalización con hv task show TASK_ID.
Utilizar la API JSON
La base es /api/v1 en el endpoint de administración. Las solicitudes autenticadas llevan un token bearer de cuenta. Un 404 puede ocultar un objeto; un 403 indica que la acción no está permitida sobre un destino visible.
Siga las tareas hasta que terminen. Las operaciones de creación e importación que lo admiten aceptan Idempotency-Key para repetir la misma petición durante su periodo de retención sin duplicarla. Reutilizar la clave con otra entrada se rechaza. No suponga que toda modificación es idempotente ni repita a ciegas una operación de disco con resultado incierto.
Conectar MCP
MCP también necesita un token de cuenta. Una configuración local por stdio utiliza:
hv mcp serve --config /etc/hv/prod.toml --stdioProporcione HV_MCP_TOKEN mediante el entorno protegido del cliente. El modo predeterminado comparte un motor existente; --engine inicia uno propio y no debe competir con hv server sobre la misma base. El modo HTTP expone otro listener /mcp y exige TLS adecuado fuera de loopback.
Las herramientas de modificación solicitan confirmación humana si el cliente admite elicitation. En caso contrario exigen confirm: true; ninguno de los mecanismos elude la autorización. Revise destino y tarea resultante.
Problemas habituales
El trabajo en cola necesita motor aunque un comando local pueda leer inventario. Una configuración incorrecta puede seleccionar otra base. Restauraciones e importaciones remotas tienen requisitos específicos en su ayuda. Ante una denegación, revise conjuntamente roles y ámbitos del token. Verifique primero una consulta de inventario antes de permitir que una automatización modifique recursos.
Elegir un comando y comprobar el resultado
Use hv --help para encontrar una familia de comandos y --help en el subcomando elegido para revisar los argumentos obligatorios. Los siguientes comandos son los utilizados en los procedimientos del manual. Conserve las opciones de conexión y autenticación del principio de este capítulo al adaptar un ejemplo. Sustituya VM, HOST y POOL por selectores reales; no son nombres de objetos que deba crear literalmente.
| Operación | Comando o familia | Comprobación |
|---|---|---|
| Listar Pools | hv pool list | El Pool previsto aparece en este despliegue. |
| Listar o consultar VM | hv vm list --pool POOL o hv vm show VM --pool POOL | Propiedad, estado y Host residente corresponden al destino. |
| Iniciar una VM | hv vm start VM --pool POOL | La VM se ejecuta y arranca su sistema operativo. |
| Apagar o reiniciar una VM | hv vm shutdown VM --pool POOL o hv vm reboot VM --pool POOL | El invitado responde y alcanza el estado solicitado. |
| Eliminar una VM | hv vm delete VM --pool POOL | Revise las consecuencias para los discos antes de confirmar y el inventario después. |
| Mover una VM en ejecución | hv vm migrate VM --pool POOL --host DESTINATION_HOST --live | La tarea termina y cambia el Host residente. |
| Entrar o salir de mantenimiento | hv host maintenance enter HOST --pool POOL o hv host maintenance exit HOST --pool POOL | Revise las VM restantes y el estado habilitado del Host. |
| Consultar o reiniciar un Host | hv host show HOST --pool POOL o hv host reboot HOST --pool POOL | Reinicie solo después de confirmar la evacuación. |
| Solicitar dom0 PV | hv host dom0-mode HOST pv --pool POOL | El modo cambia en el siguiente arranque, no inmediatamente. |
| Cambiar miembros o coordinador | hv pool eject o hv pool designate-master | Revise la ayuda y el procedimiento de Hosts antes de actuar. |
| Consultar redes | hv net list --pool POOL o hv net show NETWORK --pool POOL | Revise las conexiones físicas o superpuestas de la red elegida. |
| Crear una red | hv net create --pool POOL --name isolated --mtu 1500 | Crear el registro no proporciona rutas externas. |
| Reemplazar reglas superpuestas | hv net sdn acl set | Incluya el conjunto completo; consulte la ayuda para el formato de entrada. |
| Consultar almacenamiento | hv sr list --pool POOL o hv sr show SR --pool POOL | Revise capacidad y conexiones de Hosts. |
| Crear almacenamiento | hv sr create | Revise los argumentos del tipo elegido y los efectos destructivos antes de ejecutarlo. |
| Actualizar el inventario de almacenamiento | hv sr scan SR --pool POOL | Actualiza los registros, pero no repara datos dañados. |
| Retirar almacenamiento | hv sr forget o hv sr destroy | Forget elimina el registro; destroy destruye los datos del repositorio. |
| Consultar tareas | hv task list --pool POOL o hv task show TASK_ID | Lea el estado final y el diagnóstico, no solo la aceptación de la solicitud. |
| Consultar una tarea de copia | hv backup job show JOB | Revise VM, Remote, horario y retención. |
| Ejecutar y consultar una copia | hv backup job run JOB, hv backup run list --job JOB, hv backup run show RUN_ID | Siga la ejecución e identifique su punto de recuperación. |
| Listar y restaurar puntos | hv backup points o hv backup restore | Use modo remoto y los UUID de destino indicados en copias de seguridad. |
| Verificar la auditoría | hv audit verify | Conserve diagnósticos y anclas independientes si falla. |
La migración entre Pools añade --dest-pool DESTINATION_POOL y permite repetir --network-map VIF=NETWORK. Esta ruta utiliza el SR predeterminado del Pool de destino. No incluya correspondencias de red al migrar dentro del mismo Pool. Revise el almacenamiento y el destino de cada NIC antes de solicitar el traslado.
El procedimiento de copias incluye ejemplos completos de hv backup remote add, hv backup retention set y hv backup job create. El horario de cinco campos usa UTC. La ruta de un Remote de directorio local está en la máquina del motor, no en el equipo que envía el comando.
Usar herramientas locales del host
Estas herramientas actúan sobre el Host donde se ejecutan. Use su consola o una sesión autorizada y confirme la identidad del equipo antes de cambiarlo. No heredan un destino remoto de hv --server.
| Herramienta | Finalidad y comprobación |
|---|---|
rc-status y rc-service SERVICE status | Consultan servicios OpenRC. Use los nombres de primer arranque y seguridad. |
xl info | Consulta Xen durante el diagnóstico del arranque. |
ip address e ip route | Consultan dirección y rutas de gestión sin cambiarlas. |
hv setup-token | Emite otro token de configuración mientras no exista ninguna cuenta; mantenga privada su salida. |
hv-agent pool join-code | Genera un código público de un solo uso válido durante 15 minutos. |
hv-agent mesh status | Consulta pares de malla e información de sus conexiones. |
hv-upgrade status | Consulta las raíces de actualización y su estado. |
hv-upgrade rollback --dry-run | Muestra la reversión local prevista antes de seleccionarla. |
hv-upgrade rollback | Cambia el próximo arranque; no reinicia por sí mismo. |
hv-installer --answers /root/answers.toml --dry-run | Valida respuestas y muestra el plan sin ejecutarlo. |
hv-installer --answers /root/answers.toml | Ejecuta la instalación y borra el disco elegido sin otra confirmación de borrado. |
Antes de instalar de forma desatendida, detenga el instalador automático con rc-service hv-installer-live stop; dos instaladores no deben operar a la vez sobre el disco. Siga instalación para preparar, revisar y ejecutar en el orden correcto. El modo dry-run comprueba el plan, no si la máquina terminada podrá arrancar.
Escribir medios desde el equipo de trabajo
Los ejemplos de dd de instalación se ejecutan en el equipo que contiene la ISO, no en el Host de destino. if= indica la imagen de origen y of= el dispositivo USB completo. El tamaño de bloque se escribe bs=4M en el ejemplo Linux y bs=4m en macOS. En Linux, conv=fsync sincroniza la salida antes de terminar; espere también al comando sync posterior.
En macOS, diskutil list identifica los discos, diskutil unmountDisk desmonta el seleccionado y diskutil eject lo expulsa después de escribir y sincronizar. Compruebe el resultado de cada comando antes de continuar. Estos comandos pueden sobrescribir un disco del equipo si el destino es incorrecto. No copie un marcador de dispositivo sin sustituirlo antes por el USB que haya verificado.