Virtualization
This API is partially documented or under construction.
Overview​
API wrapper for Synology Virtual Machine Manager.
Provides methods to manage tasks, networks, storage, hosts, VMs, and images.
Parameters​
ip_address str
IP address of the Synology NAS.
port str
Port number to connect to.
username str
DSM username.
password str
DSM password.
secure bool
Use HTTPS if True. Default is False.
cert_verify bool
Verify SSL certificate if True. Default is False.
dsm_version int
DSM version. Default is 7.
debug bool
Enable debug mode. Default is True.
otp_code str
One-time password for 2FA, if required.
quickconnect_id str
QuickConnect ID for relay-based access. Defaults to None.
Methods​
get_task_list​
Get the list of virtualization tasks.
Internal API​
SYNO.Virtualization.API.Task.Info
Returns​
list of str
List of task IDs.
clear_task​
Clear a specific task by its ID.
Internal API​
SYNO.Virtualization.API.Task.Info
Parameters​
taskid str
Task ID to clear.
Returns​
dict[str, object] or str
Result of the clear operation or error message.
get_task_info​
Get information about a specific task.
Internal API​
SYNO.Virtualization.API.Task.Info
Parameters​
taskid str
Task ID to retrieve information for.
Returns​
dict[str, object] or str
Task information or error message.
get_network_group_list​
Get the list of network groups.
Internal API​
SYNO.Virtualization.API.Network
Returns​
list of dict
List of network group information.
get_storage_operation​
Get the list of storage operations.
Internal API​
SYNO.Virtualization.API.Storage
Returns​
list of str
List of storage operation information.
get_host_operation​
Get the list of host operations.
Internal API​
SYNO.Virtualization.API.Host
Returns​
list of str
List of host operation information.
get_vm_operation​
Get the list of virtual machines.
Internal API​
SYNO.Virtualization.API.Guest
Parameters​
additional bool
Whether to include additional information. Default is False.
Returns​
list of dict
List of VM information.
get_specific_vm_info​
Get information about a specific virtual machine.
Internal API​
SYNO.Virtualization.API.Guest
Parameters​
additional str or list of str
Additional fields to include.
guest_id str
Guest VM ID.
guest_name str
Guest VM name.
Returns​
dict[str, object] or str
VM information or error message.
set_vm_property​
Set properties for a virtual machine.
Internal API​
SYNO.Virtualization.API.Guest
Parameters​
guest_id str
Guest VM ID.
guest_name str
Guest VM name.
autorun int
Autorun setting (0: off, 1: last state, 2: on).
description str
VM description.
new_guest_name str
New VM name.
vcpu_num int
Number of virtual CPUs.
vram_size int
RAM size in MB.
Returns​
dict[str, object] or str
Result of the set operation or error message.
delete_vm​
Delete a virtual machine.
Internal API​
SYNO.Virtualization.API.Guest
Parameters​
guest_id str
Guest VM ID.
guest_name str
Guest VM name.
Returns​
dict[str, object] or str
Result of the delete operation or error message.
vm_power_on​
Power on a virtual machine.
Internal API​
SYNO.Virtualization.API.Guest.Action
Parameters​
guest_id str
Guest VM ID.
guest_name str
Guest VM name.
host_id str
Host ID.
host_name str
Host name.
Returns​
dict[str, object] or str
Result of the power on operation or error message.
vm_force_power_off​
Force power off a virtual machine.
Internal API​
SYNO.Virtualization.API.Guest.Action
Parameters​
guest_id str
Guest VM ID.
guest_name str
Guest VM name.
Returns​
dict[str, object] or str
Result of the power off operation or error message.
vm_shut_down​
Shut down a virtual machine.
Internal API​
SYNO.Virtualization.API.Guest.Action
Parameters​
guest_id str
Guest VM ID.
guest_name str
Guest VM name.
Returns​
dict[str, object] or str
Result of the shutdown operation or error message.
get_images_list​
Get the list of VM images.
Internal API​
SYNO.Virtualization.API.Guest.Image
Returns​
dict[str, object]
Dictionary containing image information.
delete_image​
Delete a VM image.
Internal API​
SYNO.Virtualization.API.Guest.Image
Parameters​
image_id str
Image ID.
image_name str
Image name.
Returns​
dict[str, object] or str
Result of the delete operation or error message.
create_image​
Create a new VM image.
Internal API​
SYNO.Virtualization.API.Guest.Image
Parameters​
auto_clean_task bool
Whether to auto-clean the task after creation. Default is True.
storage_names str
Storage names.
storage_ids str
Storage IDs.
type str
Image type ('disk', 'vdsm', or 'iso').
ds_file_path str
File path (should begin with a shared folder).
image_name str
Name of the image.
Returns​
dict[str, object] or str
Result of the create operation or error message.
get_snapshot_list​
Get the list of snapshots for a virtual machine.
Internal API​
SYNO.Virtualization.GuestProtect.Snap
Parameters​
guest_id str
Guest VM ID.
Returns​
dict[str, object] or str
Snapshot list (gsnaps array) or error message.
create_snapshot​
Create a snapshot of a virtual machine.
Non-blocking: returns a task_id, poll get_task_info to check completion.
Internal API​
SYNO.Virtualization.GuestProtect.Snap
Parameters​
guest_id str
Guest VM ID.
desc str
Snapshot description.
is_user_locked bool
Whether to lock the snapshot against automatic retention removal.
taken_by str
Who took the snapshot (username).
Returns​
dict[str, object] or str
Result containing task_id, or error message.
delete_snapshot​
Delete a snapshot of a virtual machine.
Non-blocking: returns a task_id. The snapshot id (gsnap_id) is obtained from
get_snapshot_list.
Internal API​
SYNO.Virtualization.GuestProtect.Snap
Parameters​
guest_id str
Guest VM ID.
gsnap_id str
Snapshot ID (from get_snapshot_list).
Returns​
dict[str, object] or str
Result containing task_id, or error message.
restore_snapshot​
Restore a virtual machine from a snapshot.
Non-blocking: returns a task_id.
Internal API​
SYNO.Virtualization.GuestProtect.Snap
Parameters​
guest_id str
Guest VM ID.
gsnap_id str
Snapshot ID (from get_snapshot_list).
is_gsnap_created bool
Whether to take a snapshot of the current state before restoring.
poweroff_guest bool
Whether to power off the guest before restoring.
Returns​
dict[str, object] or str
Result containing task_id, or error message.
create_protection_plan​
Create a VMM protection plan (Local Snapshot) for a virtual machine.
this API is implemented in version 1 only on the NAS (version 2
returns error 103 for create/delete). The guest_id parameter is
singular, not guest_ids.
Internal API​
SYNO.Virtualization.GuestProtect.Plan
Parameters​
name str
Protection plan name.
guest_id str
Guest VM ID.
Returns​
dict[str, object] or str
Result containing protect_id, or error message.
delete_protection_plan​
Delete a VMM protection plan.
this API is implemented in version 1 only on the NAS.
Internal API​
SYNO.Virtualization.GuestProtect.Plan
Parameters​
protect_id str
Protection plan ID (from create_protection_plan or list_protection_plan).
Returns​
dict[str, object] or str
Result or error message.
list_protection_plan​
List VMM protection plans.
Internal API​
SYNO.Virtualization.GuestProtect.Plan
Returns​
dict[str, object] or str
Plan list (protect_ids array) or error message.
get_host_list​
Get the list of VMM hosts (v2 API).
Internal API​
SYNO.Virtualization.Host
Returns​
dict[str, object] or str
Host list or error message.
get_host_basic_list​
Get the basic list of VMM hosts (v2 API).
Internal API​
SYNO.Virtualization.Host
Returns​
dict[str, object] or str
Basic host list or error message.
get_network_list​
Get the list of VMM networks (v2 API).
Internal API​
SYNO.Virtualization.Network
Returns​
dict[str, object] or str
Network list or error message.
get_repo_list​
Get the list of VMM repositories (v2 API).
Internal API​
SYNO.Virtualization.Repo
Returns​
dict[str, object] or str
Repository list or error message.
get_guest_list_basic​
Get the basic list of VMM guests (v2 API).
Internal API​
SYNO.Virtualization.Guest
Returns​
dict[str, object] or str
Basic guest list or error message.
get_log_list​
Get the list of VMM logs.
Internal API​
SYNO.Virtualization.Log
Returns​
dict[str, object] or str
Log list or error message.
get_setting_general​
Get the VMM general settings.
Internal API​
SYNO.Virtualization.Setting.General
Returns​
dict[str, object] or str
General settings or error message.
get_package_list​
Get the list of VMM packages.
Internal API​
SYNO.Virtualization.Package
Returns​
dict[str, object] or str
Package list or error message.
get_login_info​
Get the VMM user login information.
Internal API​
SYNO.Virtualization.User
Returns​
dict[str, object] or str
Login info or error message.
check_guest_availability​
Check guest VM availability (read-only, safe pre-flight check).
Internal API​
SYNO.Virtualization.Guest
Parameters​
guest_id str
Guest VM ID.
Returns​
dict[str, object] or str
Availability check result or error message.
snapshot_can_do​
Check whether a snapshot operation can be performed (read-only validator).
Internal API​
SYNO.Virtualization.GuestProtect.Snap
Parameters​
guest_id str
Guest VM ID.
Returns​
dict[str, object] or str
Feasibility result or error message.