0.1.8 • Published 2d ago

ts-wasm-libvirt

Licence

MIT

Version

0.1.8

Deps

Size

1.5 MB

Vulns

Weekly

Summary Dependency Versions

ts-wasm-libvirt

TypeScript-клиент для libvirt: домены, сети, хранилища, устройства, secrets, snapshots и бинарные потоки. Нативный host-пакет для поддерживаемой ОС и архитектуры устанавливается автоматически как optional dependency.

Установка и зависимости

Нужны Node.js 20+ и установленная системная библиотека libvirt. Для соединения с локальным QEMU также должен работать демон libvirt, а у пользователя должен быть доступ к его сокету.

Debian/Ubuntu:

sudo apt install libvirt0 libvirt-daemon-system
npm install ts-wasm-libvirt

Для проверки без гипервизора используйте URI test:///default. На Linux доступны готовые host-пакеты для x64 и arm64; на macOS — для arm64.

Все методы ниже принадлежат LibvirtClient, который создаётся функцией createLibvirtClient. Во всех примерах предполагается следующий контекст; закрывайте клиент в finally.

import { createLibvirtClient } from "ts-wasm-libvirt";

const client = await createLibvirtClient({ uri: "qemu:///system" });
const domain = { name: "my-vm" };
const network = { name: "default" };
const hostInterface = { name: "eth0" };
const pool = { name: "default-pool" };
const volume = { path: "/var/lib/libvirt/images/my-vm.qcow2" };
const networkFilter = { name: "my-filter" };
const secret = { uuid: "11111111-2222-3333-4444-555555555555" };
const domainXml = "<domain type='kvm'><name>my-vm</name></domain>";
const networkXml = "<network><name>my-network</name></network>";
const interfaceXml = "<interface type='ethernet'><name>eth0</name></interface>";
const poolXml = "<pool type='dir'><name>my-pool</name></pool>";
const volumeXml = "<volume><name>disk.qcow2</name></volume>";
const nodeDeviceXml = "<device><name>my-device</name></device>";
const networkFilterXml = "<filter name='my-filter' chain='root'/>";
const secretXml = "<secret ephemeral='no' private='no'/>";
const snapshotXml = "<domainsnapshot><name>before-update</name></domainsnapshot>";

try {
  // Use one or more methods from this catalogue.
} finally {
  await client.close();
}

createLibvirtClient(options) — создаёт клиент и запускает нативный host process.

const client = await createLibvirtClient({
  uri: "qemu:///system",
  defaultTimeoutMs: 5_000,
});

Аутентификация и LibvirtCredentialType

import { LibvirtCredentialType, createLibvirtClient } from "ts-wasm-libvirt";

const client = await createLibvirtClient({
  uri: "qemu+ssh://host/system",
  auth: {
    credentialTypes: [LibvirtCredentialType.AuthName, LibvirtCredentialType.Passphrase],
    callback(credentials) {
      return credentials.map((credential) => credential.defaultResult);
    },
  },
});

Возможности API

Селекторы выбирают ресурс по одному идентификатору: домен — { name } или { uuid }, сеть — { name } или { uuid }, pool — { name }, { uuid } или { path }, volume — { key } или { path }. Опциональный последний аргумент options принимает timeoutMs и signal; методы с флагами также принимают flags.

Подключение и базовые операции

health(options?: OperationOptions): Promise — Проверяет состояние соединения.

const result = await client.health();
console.log(result);

listDomains(options?: OperationOptions): Promise — Получает активные и неактивные домены.

const result = await client.listDomains();
console.log(result);

getDomain(selector: DomainSelector, options?: OperationOptions): Promise — Находит один домен.

const result = await client.getDomain(domain);
console.log(result);

getDomainXml(selector: DomainSelector, options?: OperationOptions): Promise — Возвращает XML-описание домена от libvirt.

const result = await client.getDomainXml(domain);
console.log(result);

defineDomain(xml: string, options?: FlagOperationOptions): Promise — Создаёт или обновляет persistent-домен из XML.

const result = await client.defineDomain(domainXml);
console.log(result);

undefineDomain(selector: DomainSelector, options?: FlagOperationOptions): Promise — Удаляет persistent-определение домена, но не его storage.

await client.undefineDomain(domain);

startDomain(selector: DomainSelector, options?: FlagOperationOptions): Promise — Запускает неактивный домен.

const result = await client.startDomain(domain);
console.log(result);

shutdownDomain(selector: DomainSelector, options?: FlagOperationOptions): Promise — Запрашивает мягкое выключение гостя.

const result = await client.shutdownDomain(domain);
console.log(result);

destroyDomain(selector: DomainSelector, options?: FlagOperationOptions): Promise — Принудительно останавливает домен.

const result = await client.destroyDomain(domain);
console.log(result);

rebootDomain(selector: DomainSelector, options?: OperationOptions): Promise — Перезагружает активный домен стандартным механизмом libvirt.

const result = await client.rebootDomain(domain);
console.log(result);

Домены: жизненный цикл, устройства и миграция

getDomainInfo(selector: DomainSelector, options?: OperationOptions): Promise — Возвращает подробную runtime-информацию домена.

const result = await client.getDomainInfo(domain);
console.log(result);

suspendDomain(selector: DomainSelector, options?: OperationOptions): Promise — Приостанавливает активный домен.

const result = await client.suspendDomain(domain);
console.log(result);

resumeDomain(selector: DomainSelector, options?: OperationOptions): Promise — Возобновляет приостановленный домен.

const result = await client.resumeDomain(domain);
console.log(result);

resetDomain(selector: DomainSelector, options?: OperationOptions): Promise — Выполняет немедленный reset активного домена.

const result = await client.resetDomain(domain);
console.log(result);

getDomainAutostart(selector: DomainSelector, options?: OperationOptions): Promise — Возвращает признак автоматического запуска домена.

const result = await client.getDomainAutostart(domain);
console.log(result);

setDomainAutostart(selector: DomainSelector, autostart: boolean, options?: OperationOptions): Promise — Включает или выключает автоматический запуск домена.

await client.setDomainAutostart(domain, true);

isDomainActive(selector: DomainSelector, options?: OperationOptions): Promise — Проверяет, активен ли домен.

const result = await client.isDomainActive(domain);
console.log(result);

isDomainPersistent(selector: DomainSelector, options?: OperationOptions): Promise — Проверяет, имеет ли домен persistent-определение.

const result = await client.isDomainPersistent(domain);
console.log(result);

getDomainOsType(selector: DomainSelector, options?: OperationOptions): Promise — Возвращает тип гостевой ОС, например `hvm` или `linux`.

const result = await client.getDomainOsType(domain);
console.log(result);

getDomainHostname(selector: DomainSelector, options?: FlagOperationOptions): Promise — Возвращает hostname гостя средствами поддерживающего это driver.

const result = await client.getDomainHostname(domain);
console.log(result);

getDomainMaxMemory(selector: DomainSelector, options?: OperationOptions): Promise — Возвращает максимальную память домена в KiB без потери точности.

const result = await client.getDomainMaxMemory(domain);
console.log(result);

setDomainMemory(selector: DomainSelector, memoryKiB: number | bigint, options?: OperationOptions): Promise — Изменяет текущую память домена в KiB.

await client.setDomainMemory(domain, 2_097_152);

setDomainMaxMemory(selector: DomainSelector, memoryKiB: number | bigint, options?: OperationOptions): Promise — Изменяет максимальную память домена в KiB.

await client.setDomainMaxMemory(domain, 2_097_152);

getDomainMaxVcpus(selector: DomainSelector, options?: OperationOptions): Promise — Возвращает максимально поддерживаемое число vCPU домена.

const result = await client.getDomainMaxVcpus(domain);
console.log(result);

setDomainVcpus(selector: DomainSelector, vcpus: number, options?: OperationOptions): Promise — Изменяет число vCPU домена.

await client.setDomainVcpus(domain, 2);

createTransientDomain(xml: string, options?: FlagOperationOptions): Promise — Создаёт transient-домен из XML без persistent-определения.

const result = await client.createTransientDomain(domainXml);
console.log(result);

isDomainUpdated(selector: DomainSelector, options?: OperationOptions): Promise — Проверяет, изменилось ли persistent-определение домена.

const result = await client.isDomainUpdated(domain);
console.log(result);

wakeupDomain(selector: DomainSelector, options?: FlagOperationOptions): Promise — Выводит домен из PM suspend через `Domain::pm_wakeup`.

const result = await client.wakeupDomain(domain);
console.log(result);

getDomainVcpusFlags(selector: DomainSelector, options?: FlagOperationOptions): Promise — Возвращает число vCPU для указанной маски `virDomainVcpuFlags`.

const result = await client.getDomainVcpusFlags(domain);
console.log(result);

setDomainVcpusFlags(selector: DomainSelector, vcpus: number, options?: FlagOperationOptions): Promise — Изменяет число vCPU с указанной маской `virDomainVcpuFlags`.

await client.setDomainVcpusFlags(domain, 2);

getDomainTime(selector: DomainSelector, options?: FlagOperationOptions): Promise — Возвращает виртуальные часы домена.

const result = await client.getDomainTime(domain);
console.log(result);

setDomainTime(selector: DomainSelector, time: DomainTime, options?: FlagOperationOptions): Promise — Устанавливает виртуальные часы домена.

await client.setDomainTime(domain, { seconds: 0n, nanoseconds: 0 });

getDomainBlockInfo(selector: DomainSelector, disk: string, options?: FlagOperationOptions): Promise — Возвращает capacity/allocation/physical для block device.

const result = await client.getDomainBlockInfo(domain, "vda");
console.log(result);

getDomainBlockStats(selector: DomainSelector, disk: string, options?: OperationOptions): Promise — Возвращает I/O-счётчики block device.

const result = await client.getDomainBlockStats(domain, "vda");
console.log(result);

resizeDomainBlock(selector: DomainSelector, disk: string, size: number | bigint, options?: FlagOperationOptions): Promise

— Изменяет логический размер block device в байтах.

await client.resizeDomainBlock(domain, "vda", 10_737_418_240n);

getDomainInterfaceStats(selector: DomainSelector, path: string, options?: OperationOptions): Promise — Возвращает сетевые счётчики interface домена.

const result = await client.getDomainInterfaceStats(hostInterface, "/var/lib/libvirt/images/my-vm.qcow2");
console.log(result);

getDomainMemoryStats(selector: DomainSelector, options?: FlagOperationOptions): Promise — Возвращает tagged memory statistics домена.

const result = await client.getDomainMemoryStats(domain);
console.log(result);

getDomainInterfaceAddresses(selector: DomainSelector, source: number, options?: FlagOperationOptions): Promise — Возвращает адреса гостевых interfaces из выбранного libvirt source.

const result = await client.getDomainInterfaceAddresses(hostInterface, 0);
console.log(result);

getDomainMemoryParameters(selector: DomainSelector, options?: FlagOperationOptions): Promise — Возвращает typed memory parameters домена.

const result = await client.getDomainMemoryParameters(domain);
console.log(result);

setDomainMemoryParameters(selector: DomainSelector, parameters: DomainMemoryParameters, options?: FlagOperationOptions): Promise

— Изменяет переданные typed memory parameters домена.

await client.setDomainMemoryParameters(domain, { /* typed parameters */ });

getDomainNumaParameters(selector: DomainSelector, options?: FlagOperationOptions): Promise — Возвращает NUMA policy домена.

const result = await client.getDomainNumaParameters(domain);
console.log(result);

setDomainNumaParameters(selector: DomainSelector, parameters: DomainNumaParameters, options?: FlagOperationOptions): Promise

— Изменяет переданные NUMA parameters домена.

await client.setDomainNumaParameters(domain, { /* typed parameters */ });

pinDomainVcpu(selector: DomainSelector, vcpu: number, cpuMap: Uint8Array, options?: FlagOperationOptions): Promise — Закрепляет один vCPU за bitmap физических CPU.

await client.pinDomainVcpu(domain, 0, new Uint8Array([0b0000_0011]));

pinDomainEmulator(selector: DomainSelector, cpuMap: Uint8Array, options?: FlagOperationOptions): Promise — Закрепляет emulator thread домена за bitmap физических CPU.

await client.pinDomainEmulator(domain, new Uint8Array([0b0000_0011]));

sendDomainKey(selector: DomainSelector, codeSet: number, holdTimeMs: number, keycodes: readonly number[], options?: FlagOperationOptions): Promise

— Отправляет гостю последовательность keycodes.

await client.sendDomainKey(domain, 0, 100, [30]);

getDomainSchedulerParameters(selector: DomainSelector, options?: FlagOperationOptions): Promise — Возвращает scheduler type и typed scheduler parameters домена.

const result = await client.getDomainSchedulerParameters(domain);
console.log(result);

setDomainSchedulerParameters(selector: DomainSelector, parameters: DomainSchedulerParameters, options?: FlagOperationOptions): Promise

— Изменяет переданные scheduler parameters домена.

await client.setDomainSchedulerParameters(domain, { /* typed parameters */ });

getDomainJobInfo(selector: DomainSelector, options?: OperationOptions): Promise — Возвращает legacy job information текущей длительной операции.

const result = await client.getDomainJobInfo(domain);
console.log(result);

getDomainJobStats(selector: DomainSelector, options?: FlagOperationOptions): Promise — Возвращает typed job statistics текущей длительной операции.

const result = await client.getDomainJobStats(domain);
console.log(result);

attachDomainDevice(selector: DomainSelector, xml: string, options?: FlagOperationOptions): Promise — Подключает устройство, описанное XML, к домену.

const result = await client.attachDomainDevice(domain, domainXml);
console.log(result);

detachDomainDevice(selector: DomainSelector, xml: string, options?: FlagOperationOptions): Promise — Отключает устройство, описанное XML, от домена.

const result = await client.detachDomainDevice(domain, domainXml);
console.log(result);

updateDomainDevice(selector: DomainSelector, xml: string, options?: FlagOperationOptions): Promise — Обновляет существующее устройство домена из XML.

const result = await client.updateDomainDevice(domain, domainXml);
console.log(result);

managedSaveDomain(selector: DomainSelector, options?: FlagOperationOptions): Promise — Сохраняет runtime-состояние домена в managed save image.

await client.managedSaveDomain(domain);

hasDomainManagedSave(selector: DomainSelector, options?: FlagOperationOptions): Promise — Проверяет наличие managed save image домена.

const result = await client.hasDomainManagedSave(domain);
console.log(result);

removeDomainManagedSave(selector: DomainSelector, options?: FlagOperationOptions): Promise — Удаляет managed save image домена.

await client.removeDomainManagedSave(domain);

coreDumpDomain(selector: DomainSelector, path: string, format?: number, options?: FlagOperationOptions): Promise — Записывает core dump домена в файл native host.

await client.coreDumpDomain(domain, "/var/lib/libvirt/images/my-vm.qcow2");

getDomainMetadata(selector: DomainSelector, kind: number, options?: DomainMetadataOptions): Promise — Возвращает metadata выбранного типа и namespace.

const result = await client.getDomainMetadata(domain, 0);
console.log(result);

setDomainMetadata(selector: DomainSelector, kind: number, metadata: string | null, options?: SetDomainMetadataOptions): Promise

— Устанавливает или удаляет metadata выбранного типа и namespace.

await client.setDomainMetadata(domain, 0, "<metadata/>");

renameDomain(selector: DomainSelector, newName: string, options?: FlagOperationOptions): Promise — Переименовывает persistent-домен.

const result = await client.renameDomain(domain, "renamed-vm");
console.log(result);

setDomainUserPassword(selector: DomainSelector, user: string, password: string, options?: FlagOperationOptions): Promise — Устанавливает пароль пользователя внутри гостя через guest agent/driver.

await client.setDomainUserPassword(domain, "guest-user", "secret");

qemuMonitorCommand(selector: DomainSelector, command: string, options?: FlagOperationOptions): Promise — Выполняет QEMU monitor command и возвращает сырой ответ.

const result = await client.qemuMonitorCommand(domain, "query-status");
console.log(result);

qemuAgentCommand(selector: DomainSelector, command: string, timeout?: number, options?: FlagOperationOptions): Promise — Выполняет QEMU guest agent command и возвращает сырой ответ.

const result = await client.qemuAgentCommand(domain, "query-status");
console.log(result);

restoreDomain(path: string, xml?: string, options?: FlagOperationOptions): Promise — Восстанавливает домен из save image на файловой системе native host.

await client.restoreDomain("/var/lib/libvirt/images/my-vm.qcow2");

getDomainSaveImageXml(path: string, options?: FlagOperationOptions): Promise — Возвращает XML определения, сохранённого в domain save image.

const result = await client.getDomainSaveImageXml("/var/lib/libvirt/images/my-vm.qcow2");
console.log(result);

setDomainSaveImageXml(path: string, xml: string, options?: FlagOperationOptions): Promise — Заменяет XML определения в domain save image.

await client.setDomainSaveImageXml("/var/lib/libvirt/images/my-vm.qcow2", domainXml);

migrateDomainToUri(selector: DomainSelector, destinationUri: string, options?: DomainMigrationOptions): Promise — Мигрирует домен непосредственно в destination URI.

await client.migrateDomainToUri(domain, "qemu+ssh://destination/system");

migrateDomainToConnection(selector: DomainSelector, destinationUri: string, options?: DomainMigrationOptions): Promise — Открывает второй `virt::Connect` в native host и мигрирует домен в него.

const result = await client.migrateDomainToConnection(domain, "qemu+ssh://destination/system");
console.log(result);

screenshotDomain(selector: DomainSelector, options?: DomainScreenshotOptions): Promise — Снимает экран домена и возвращает read-only бинарный поток изображения.

const stream = await client.screenshotDomain(domain);
// Read: for await (const chunk of stream) { /* Buffer */ }
// Write: stream.write(data); stream.end();
await stream.finish();

openDomainConsole(selector: DomainSelector, options?: DomainStreamOptions): Promise — Открывает двунаправленную console домена через `Domain::open_console`.

const stream = await client.openDomainConsole(domain);
// Read: for await (const chunk of stream) { /* Buffer */ }
// Write: stream.write(data); stream.end();
await stream.finish();

openDomainChannel(selector: DomainSelector, options?: DomainStreamOptions): Promise — Открывает двунаправленный guest channel через `Domain::open_channel`.

const stream = await client.openDomainChannel(domain);
// Read: for await (const chunk of stream) { /* Buffer */ }
// Write: stream.write(data); stream.end();
await stream.finish();

openDomainGraphics(selector: DomainSelector, options?: DomainGraphicsOptions): Promise — Открывает graphics socket домена как двунаправленный поток Node.js.

const stream = await client.openDomainGraphics(domain);
// Read: for await (const chunk of stream) { /* Buffer */ }
// Write: stream.write(data); stream.end();
await stream.finish();

Соединение, compute node и CPU

getCapabilities(options?: OperationOptions): Promise — Возвращает XML capabilities текущего libvirt connection.

const result = await client.getCapabilities();
console.log(result);

getConnectionHostname(options?: OperationOptions): Promise — Возвращает hostname compute node.

const result = await client.getConnectionHostname();
console.log(result);

getLibvirtVersion(options?: OperationOptions): Promise — Возвращает числовую версию системной библиотеки libvirt.

const result = await client.getLibvirtVersion();
console.log(result);

getHypervisorVersion(options?: OperationOptions): Promise — Возвращает числовую версию hypervisor driver.

const result = await client.getHypervisorVersion();
console.log(result);

getSystemInfo(options?: FlagOperationOptions): Promise — Возвращает XML или driver-specific system information.

const result = await client.getSystemInfo();
console.log(result);

isConnectionSecure(options?: OperationOptions): Promise — Проверяет, считается ли transport соединения безопасным.

const result = await client.isConnectionSecure();
console.log(result);

isConnectionEncrypted(options?: OperationOptions): Promise — Проверяет, зашифрован ли transport соединения.

const result = await client.isConnectionEncrypted();
console.log(result);

getFreeMemory(options?: OperationOptions): Promise — Возвращает свободную память compute node в байтах.

const result = await client.getFreeMemory();
console.log(result);

getMaxVcpus(domainType?: string, options?: OperationOptions): Promise — Возвращает максимальное число vCPU для указанного domain type.

const result = await client.getMaxVcpus();
console.log(result);

getNodeInfo(options?: OperationOptions): Promise — Возвращает topology и память compute node.

const result = await client.getNodeInfo();
console.log(result);

getCpuModels(architecture: string, options?: FlagOperationOptions): Promise — Возвращает CPU models, поддерживаемые указанной архитектурой.

const result = await client.getCpuModels("x86_64");
console.log(result);

compareCpu(xml: string, options?: FlagOperationOptions): Promise — Сравнивает CPU XML с CPU compute node и возвращает код libvirt.

const result = await client.compareCpu(domainXml);
console.log(result);

baselineCpu(xmlCpus: readonly string[], options?: FlagOperationOptions): Promise — Формирует общий baseline CPU XML из нескольких CPU definitions.

const result = await client.baselineCpu([domainXml]);
console.log(result);

getDomainCapabilities(options?: DomainCapabilitiesOptions): Promise — Возвращает domain capabilities XML для заданных фильтров.

const result = await client.getDomainCapabilities();
console.log(result);

domainXmlFromNative(format: string, config: string, options?: FlagOperationOptions): Promise — Преобразует native hypervisor config в domain XML.

const result = await client.domainXmlFromNative("qemu", "native configuration");
console.log(result);

domainXmlToNative(format: string, xml: string, options?: FlagOperationOptions): Promise — Преобразует domain XML в native hypervisor config.

const result = await client.domainXmlToNative("qemu", domainXml);
console.log(result);

setConnectionKeepalive(interval: number, count: number, options?: OperationOptions): Promise — Настраивает keepalive interval и допустимое число пропусков.

const result = await client.setConnectionKeepalive(5, 3);
console.log(result);

getCellsFreeMemory(startCell: number, maxCells: number, options?: OperationOptions): Promise — Возвращает свободную память последовательности NUMA cells.

const result = await client.getCellsFreeMemory(0, 2);
console.log(result);

getFreePages(pageSizesKiB: readonly number[], startCell: number, cellCount: number, options?: FlagOperationOptions): Promise

— Возвращает количество свободных pages заданных размеров по NUMA cells.

const result = await client.getFreePages([4], 0, 2);
console.log(result);

findStoragePoolSources(kind: string, spec?: string, options?: FlagOperationOptions): Promise — Возвращает XML найденных storage pool sources указанного типа.

const result = await client.findStoragePoolSources(0);
console.log(result);

Сети

listNetworks(options?: OperationOptions): Promise — Возвращает активные и неактивные libvirt networks.

const result = await client.listNetworks();
console.log(result);

getNetwork(selector: NetworkSelector, options?: OperationOptions): Promise — Находит одну network по имени или UUID.

const result = await client.getNetwork(network);
console.log(result);

getNetworkXml(selector: NetworkSelector, options?: FlagOperationOptions): Promise — Возвращает XML выбранной network.

const result = await client.getNetworkXml(network);
console.log(result);

defineNetwork(xml: string, options?: OperationOptions): Promise — Создаёт persistent network definition из XML.

const result = await client.defineNetwork(networkXml);
console.log(result);

createNetwork(xml: string, options?: OperationOptions): Promise — Создаёт и запускает transient network из XML.

const result = await client.createNetwork(networkXml);
console.log(result);

startNetwork(selector: NetworkSelector, options?: OperationOptions): Promise — Запускает определённую неактивную network.

const result = await client.startNetwork(network);
console.log(result);

destroyNetwork(selector: NetworkSelector, options?: OperationOptions): Promise — Немедленно останавливает активную network.

await client.destroyNetwork(network);

undefineNetwork(selector: NetworkSelector, options?: OperationOptions): Promise — Удаляет persistent network definition.

await client.undefineNetwork(network);

setNetworkAutostart(selector: NetworkSelector, autostart: boolean, options?: OperationOptions): Promise — Включает или выключает autostart network.

await client.setNetworkAutostart(network, true);

getNetworkBridgeName(selector: NetworkSelector, options?: OperationOptions): Promise — Возвращает имя bridge, связанного с network.

const result = await client.getNetworkBridgeName(network);
console.log(result);

updateNetwork(selector: NetworkSelector, xml: string, options: NetworkUpdateOptions): Promise — Обновляет выбранную секцию network XML.

await client.updateNetwork(network, networkXml, { command: 0, section: 0 });

Интерфейсы хоста

listInterfaces(options?: OperationOptions): Promise — Возвращает активные и неактивные host interfaces.

const result = await client.listInterfaces();
console.log(result);

getInterface(selector: InterfaceSelector, options?: OperationOptions): Promise — Находит host interface по имени или MAC-адресу.

const result = await client.getInterface(hostInterface);
console.log(result);

getInterfaceXml(selector: InterfaceSelector, options?: FlagOperationOptions): Promise — Возвращает XML выбранного host interface.

const result = await client.getInterfaceXml(hostInterface);
console.log(result);

defineInterface(xml: string, options?: FlagOperationOptions): Promise — Создаёт persistent host interface definition из XML.

const result = await client.defineInterface(interfaceXml);
console.log(result);

startInterface(selector: InterfaceSelector, options?: FlagOperationOptions): Promise — Активирует определённый host interface.

const result = await client.startInterface(hostInterface);
console.log(result);

destroyInterface(selector: InterfaceSelector, options?: FlagOperationOptions): Promise — Деактивирует host interface.

const result = await client.destroyInterface(hostInterface);
console.log(result);

undefineInterface(selector: InterfaceSelector, options?: OperationOptions): Promise — Удаляет persistent host interface definition.

await client.undefineInterface(hostInterface);

Storage pools и volumes

listStoragePools(options?: OperationOptions): Promise — Возвращает активные и неактивные storage pools.

const result = await client.listStoragePools();
console.log(result);

getStoragePool(selector: StoragePoolSelector, options?: OperationOptions): Promise — Находит storage pool по имени, UUID или target path.

const result = await client.getStoragePool(pool);
console.log(result);

getStoragePoolXml(selector: StoragePoolSelector, options?: FlagOperationOptions): Promise — Возвращает XML выбранного storage pool.

const result = await client.getStoragePoolXml(pool);
console.log(result);

defineStoragePool(xml: string, options?: FlagOperationOptions): Promise — Создаёт persistent storage pool definition из XML.

const result = await client.defineStoragePool(poolXml);
console.log(result);

createStoragePool(xml: string, options?: FlagOperationOptions): Promise — Создаёт и запускает transient storage pool из XML.

const result = await client.createStoragePool(poolXml);
console.log(result);

startStoragePool(selector: StoragePoolSelector, options?: FlagOperationOptions): Promise — Запускает определённый storage pool.

const result = await client.startStoragePool(pool);
console.log(result);

buildStoragePool(selector: StoragePoolSelector, options?: FlagOperationOptions): Promise — Создаёт backing storage для pool.

const result = await client.buildStoragePool(pool);
console.log(result);

refreshStoragePool(selector: StoragePoolSelector, options?: FlagOperationOptions): Promise — Перечитывает список volumes и состояние storage pool.

const result = await client.refreshStoragePool(pool);
console.log(result);

destroyStoragePool(selector: StoragePoolSelector, options?: OperationOptions): Promise — Останавливает активный storage pool без удаления данных.

await client.destroyStoragePool(pool);

deleteStoragePool(selector: StoragePoolSelector, options?: FlagOperationOptions): Promise — Удаляет backing storage pool согласно flags.

await client.deleteStoragePool(pool);

undefineStoragePool(selector: StoragePoolSelector, options?: OperationOptions): Promise — Удаляет persistent storage pool definition.

await client.undefineStoragePool(pool);

setStoragePoolAutostart(selector: StoragePoolSelector, autostart: boolean, options?: OperationOptions): Promise — Включает или выключает autostart storage pool.

await client.setStoragePoolAutostart(pool, true);

listStorageVolumes(selector: StoragePoolSelector, options?: OperationOptions): Promise — Возвращает volumes выбранного storage pool.

const result = await client.listStorageVolumes(volume);
console.log(result);

getStoragePoolByVolume(selector: StorageVolumeSelector, options?: OperationOptions): Promise — Находит storage pool, которому принадлежит volume.

const result = await client.getStoragePoolByVolume(volume);
console.log(result);

getStorageVolume(selector: StorageVolumeSelector, options?: OperationOptions): Promise — Находит storage volume по глобальному key или path.

const result = await client.getStorageVolume(volume);
console.log(result);

getStorageVolumeXml(selector: StorageVolumeSelector, options?: FlagOperationOptions): Promise — Возвращает XML выбранного storage volume.

const result = await client.getStorageVolumeXml(volume);
console.log(result);

createStorageVolume(pool: StoragePoolSelector, xml: string, options?: FlagOperationOptions): Promise — Создаёт storage volume из XML внутри выбранного pool.

const result = await client.createStorageVolume(pool, volumeXml);
console.log(result);

deleteStorageVolume(selector: StorageVolumeSelector, options?: FlagOperationOptions): Promise — Удаляет storage volume согласно flags.

await client.deleteStorageVolume(volume);

wipeStorageVolume(selector: StorageVolumeSelector, options?: FlagOperationOptions): Promise — Перезаписывает содержимое volume стандартным wipe algorithm.

await client.wipeStorageVolume(volume);

resizeStorageVolume(selector: StorageVolumeSelector, capacity: number | bigint, options?: FlagOperationOptions): Promise — Изменяет логическую ёмкость storage volume в байтах.

await client.resizeStorageVolume(volume, 10_737_418_240n);

getStorageVolumeByName(pool: StoragePoolSelector, name: string, options?: OperationOptions): Promise — Находит volume по имени внутри выбранного pool.

const result = await client.getStorageVolumeByName(pool, "resource-name");
console.log(result);

cloneStorageVolume(pool: StoragePoolSelector, xml: string, source: StorageVolumeSelector, options?: FlagOperationOptions): Promise

— Клонирует source volume в новый volume, описанный XML.

const result = await client.cloneStorageVolume(pool, volumeXml, volume);
console.log(result);

wipeStorageVolumePattern(selector: StorageVolumeSelector, algorithm: number, options?: FlagOperationOptions): Promise — Перезаписывает volume выбранным `virStorageVolWipeAlgorithm`.

await client.wipeStorageVolumePattern(volume, 0);

downloadStorageVolume(selector: StorageVolumeSelector, options?: StorageVolumeTransferOptions): Promise — Загружает диапазон volume из libvirt в read-only поток Node.js.

const stream = await client.downloadStorageVolume(volume);
// Read: for await (const chunk of stream) { /* Buffer */ }
// Write: stream.write(data); stream.end();
await stream.finish();

uploadStorageVolume(selector: StorageVolumeSelector, options?: StorageVolumeTransferOptions): Promise — Создаёт writable-поток для загрузки данных в volume через libvirt.

const stream = await client.uploadStorageVolume(volume);
// Read: for await (const chunk of stream) { /* Buffer */ }
// Write: stream.write(data); stream.end();
await stream.finish();

Устройства хоста

listNodeDevices(options?: OperationOptions): Promise — Возвращает node devices compute node.

const result = await client.listNodeDevices();
console.log(result);

getNodeDevice(name: string, options?: OperationOptions): Promise — Находит node device по уникальному имени.

const result = await client.getNodeDevice("resource-name");
console.log(result);

getNodeDeviceXml(name: string, options?: FlagOperationOptions): Promise — Возвращает XML выбранного node device.

const result = await client.getNodeDeviceXml("resource-name");
console.log(result);

createNodeDevice(xml: string, options?: FlagOperationOptions): Promise — Создаёт node device из XML.

const result = await client.createNodeDevice(nodeDeviceXml);
console.log(result);

destroyNodeDevice(name: string, options?: OperationOptions): Promise — Уничтожает созданный node device.

await client.destroyNodeDevice("resource-name");

detachNodeDevice(name: string, options?: OperationOptions): Promise — Отсоединяет node device от host driver.

const result = await client.detachNodeDevice("resource-name");
console.log(result);

resetNodeDevice(name: string, options?: OperationOptions): Promise — Сбрасывает node device.

const result = await client.resetNodeDevice("resource-name");
console.log(result);

reattachNodeDevice(name: string, options?: OperationOptions): Promise — Повторно присоединяет node device к host driver.

const result = await client.reattachNodeDevice("resource-name");
console.log(result);

getScsiHostNodeDevice(wwnn: string, wwpn: string, options?: FlagOperationOptions): Promise — Находит SCSI host device по WWNN и WWPN.

const result = await client.getScsiHostNodeDevice("50014380242b9751", "50014380242b9752");
console.log(result);

detachNodeDeviceFlags(name: string, driver?: string, options?: FlagOperationOptions): Promise — Отсоединяет node device с явным driver и flags.

const result = await client.detachNodeDeviceFlags("resource-name");
console.log(result);

countNodeDevices(capability?: string, options?: FlagOperationOptions): Promise — Считает node devices, необязательно фильтруя по capability.

const result = await client.countNodeDevices();
console.log(result);

Network filters

listNetworkFilters(options?: OperationOptions): Promise — Возвращает все network filters.

const result = await client.listNetworkFilters();
console.log(result);

getNetworkFilter(selector: NetworkFilterSelector, options?: OperationOptions): Promise — Находит network filter по имени или UUID.

const result = await client.getNetworkFilter(networkFilter);
console.log(result);

getNetworkFilterXml(selector: NetworkFilterSelector, options?: FlagOperationOptions): Promise — Возвращает XML выбранного network filter.

const result = await client.getNetworkFilterXml(networkFilter);
console.log(result);

defineNetworkFilter(xml: string, options?: OperationOptions): Promise — Создаёт или обновляет network filter из XML.

const result = await client.defineNetworkFilter(networkFilterXml);
console.log(result);

undefineNetworkFilter(selector: NetworkFilterSelector, options?: OperationOptions): Promise — Удаляет persistent network filter.

await client.undefineNetworkFilter(networkFilter);

Secrets

listSecrets(options?: OperationOptions): Promise — Возвращает metadata всех secrets без их значений.

const result = await client.listSecrets();
console.log(result);

getSecret(selector: SecretSelector, options?: OperationOptions): Promise — Находит secret по UUID либо usage type/ID.

const result = await client.getSecret(secret);
console.log(result);

getSecretXml(selector: SecretSelector, options?: FlagOperationOptions): Promise — Возвращает XML metadata выбранного secret.

const result = await client.getSecretXml(secret);
console.log(result);

defineSecret(xml: string, options?: FlagOperationOptions): Promise — Создаёт или обновляет secret definition из XML.

const result = await client.defineSecret(secretXml);
console.log(result);

getSecretValue(selector: SecretSelector, options?: FlagOperationOptions): Promise — Возвращает бинарное значение secret; не логируйте результат.

const result = await client.getSecretValue(secret);
console.log(result);

setSecretValue(selector: SecretSelector, value: Uint8Array, options?: FlagOperationOptions): Promise — Устанавливает бинарное значение secret.

await client.setSecretValue(secret, new Uint8Array([1, 2, 3]));

undefineSecret(selector: SecretSelector, options?: OperationOptions): Promise — Удаляет secret definition и его значение.

await client.undefineSecret(secret);

Снимки доменов и закрытие

listDomainSnapshots(domain: DomainSelector, options?: FlagOperationOptions): Promise — Возвращает snapshots выбранного домена.

const result = await client.listDomainSnapshots(domain);
console.log(result);

getDomainSnapshot(domain: DomainSelector, name: string, options?: FlagOperationOptions): Promise — Находит snapshot домена по имени.

const result = await client.getDomainSnapshot(domain, "resource-name");
console.log(result);

getDomainSnapshotXml(domain: DomainSelector, name: string, options?: FlagOperationOptions): Promise — Возвращает XML выбранного snapshot.

const result = await client.getDomainSnapshotXml(domain, "resource-name");
console.log(result);

createDomainSnapshot(domain: DomainSelector, xml: string, options?: FlagOperationOptions): Promise — Создаёт snapshot домена из XML.

const result = await client.createDomainSnapshot(domain, snapshotXml);
console.log(result);

getCurrentDomainSnapshot(domain: DomainSelector, options?: FlagOperationOptions): Promise — Возвращает текущий snapshot домена.

const result = await client.getCurrentDomainSnapshot(domain);
console.log(result);

revertDomainSnapshot(domain: DomainSelector, name: string, options?: FlagOperationOptions): Promise — Возвращает домен к состоянию выбранного snapshot.

const result = await client.revertDomainSnapshot(domain, "resource-name");
console.log(result);

deleteDomainSnapshot(domain: DomainSelector, name: string, options?: FlagOperationOptions): Promise — Удаляет snapshot согласно flags.

await client.deleteDomainSnapshot(domain, "resource-name");

listDomainSnapshotChildren(domain: DomainSelector, name: string, options?: FlagOperationOptions): Promise — Возвращает непосредственные дочерние snapshots.

const result = await client.listDomainSnapshotChildren(domain, "resource-name");
console.log(result);

getDomainSnapshotParent(domain: DomainSelector, name: string, options?: FlagOperationOptions): Promise — Возвращает родительский snapshot.

const result = await client.getDomainSnapshotParent(domain, "resource-name");
console.log(result);

close(): Promise — Закрывает соединение и native host. Метод идемпотентен.

await client.close();

Ошибки и потоки

LibvirtAdapterError — ошибка операции с машинно-читаемым полем code.

import { LibvirtAdapterError } from "ts-wasm-libvirt";

try {
  await client.getDomain({ name: "missing-vm" });
} catch (error) {
  if (error instanceof LibvirtAdapterError && error.code === "NOT_FOUND") {
    console.log("Домен не найден");
  }
}

Коды: INITIALIZATION_FAILED, HOST_ERROR, INVALID_ARGUMENT, NOT_FOUND, CONFLICT, INVALID_DEFINITION, CANCELLED, TIMEOUT.

LibvirtBinaryStream.finish() — подтверждает успешное окончание работы потока.

const stream = await client.uploadStorageVolume(volume, { length: 4 });
stream.end(Buffer.from([1, 2, 3, 4]));
await stream.finish();

LibvirtBinaryStream.abort() — немедленно прерывает поток.

const stream = await client.openDomainConsole(domain);
// On cancellation or error:
await stream.abort();

Значения libvirt u64, которые не всегда точны в JavaScript, возвращаются как десятичные строки UInt64String; соответствующие входные параметры принимают number | bigint.