api.vm.define

/vm/define

api.vm.define.views.vm_define_list(*args, **kwargs)

List (GET) VM definitions.

GET /vm/define
DC-bound?:
Permissions:
Asynchronous?:
Parameters:
  • data.full (boolean) – Display full VM definitions (including disk and nic lists) (default: false)
  • data.active (boolean) – Display currently active VM definitions on compute node (default: false)
  • data.order_by (string) – Available fields for sorting: hostname (default: hostname)
Status Codes:

es example:

es get /vm/define

{
    "url": "https://my.erigones.com/api/vm/define/",
    "status": 200,
    "method": "GET",
    "text": {
        "status": "SUCCESS",
        "result": [
            {
                "node": null,
                "ram": 1024,
                "hostname": "example.cust.erigones.com",
                "owner": "user@example.com",
                "alias": "example",
                "vcpus": 1,
                "template": null,
                "ostype": 1
            },
        ],
        "task_id": "0-6f75849b-71fc-44b9-a2b5"
    }
}

/vm/(hostname_or_uuid)/define

api.vm.define.views.vm_define(*args, **kwargs)

Show (GET), create (POST), change (PUT) or delete (DELETE) a VM definition.

GET /vm/(hostname_or_uuid)/define
DC-bound?:
Permissions:
Asynchronous?:
Parameters:
  • hostname_or_uuid (string) – required - Server hostname or uuid
  • data.full (boolean) – Display full VM definition (including disk and nic lists) (default: false)
  • data.active (boolean) – Display currently active VM definition on compute node (default: false)
  • data.diff (boolean) – Display differences between active VM definition on compute node and current configuration (default: false)
Status Codes:
POST /vm/(hostname_or_uuid)/define
DC-bound?:
Permissions:
Asynchronous?:
Parameters:
  • hostname_or_uuid (string) – required - Server hostname
  • data.alias (string) – Short server name (default: hostname)
  • data.template (string) – VM template name (default: null)
  • data.ostype (integer) – Operating system type (1 - Linux VM, 2 - SunOS VM, 3 - BSD VM, 4 - Windows VM, 5 - SunOS Zone, 6 - Linux Zone) (default: 1)
  • data.vcpus (integer) – required - Number of virtual CPUs inside VM (1 - 1024); This number is used to calculate an internal compute node CPU limit for the VM (cpu_cap). When the VMS_VM_CPU_CAP_REQUIRED DC setting is disabled, then the vcpus value can be 0, which will remove the compute node CPU limit entirely (SunOS and LX Zone only)
  • data.ram (integer) – required - Size of RAM inside VM (1 - 1048576 MB)
  • data.note (string) – Text note visible to every user with access to this VM (default: “”)
  • data.owner (string) – User that owns the VM (default: logged in user)
  • data.node (string) – Name of the host system (default: null => will be chosen automatically just before the VM is created)
  • data.tags (array) – Custom VM tags (default: [])
  • data.monitored (boolean) – Enable VM synchronization with monitoring system (default: true)
  • data.monitored_internal – Enable VM synchronization with internal monitoring system (requires SuperAdmin permission) (default: true)
  • data.installed (boolean) – Mark the server as installed (default: false)
  • data.snapshot_limit_manual (integer) – Maximum number of manual snapshots for this VM (default: null [unlimited])
  • data.snapshot_size_percent_limit (integer) – Maximum size of all snapshots for this VM relative to size of all defined VM disks. Ignored if snapshot_size_limit is defined (default: null [unlimited])
  • data.snapshot_size_limit (integer) – Maximum absolute size of all snapshots for this VM in megabytes (default: null [unlimited])
  • data.zpool (string) – The zpool used for the VM (default: zones)
  • data.cpu_shares (integer) – Number of VM’s CPU shares relative to other VMs (requires SuperAdmin permission) (default: 100)
  • data.zfs_io_priority (integer) – IO throttle priority relative to other VMs (requires SuperAdmin permission) (default: 100)
  • data.cpu_type (string) – KVM only; Type of the virtual CPU exposed to the VM. One of qemu64, host (default: qemu64; except for Windows ostype where the default is host)
  • data.vga (string) – KVM only; VGA emulation driver. One of std, cirrus, vmware (default: std)
  • data.bootrom (string) – BHYVE only; Default VM boot firmware. One of bios, uefi (default: bios). Only uefi mode supports VNC.
  • data.dns_domain (string) – Search domain set in /etc/hosts (SunOS Zone only, default: domain part of hostname)
  • data.routes (object) – Key-value object that maps destinations to gateways. Items will be set as static routes in the OS (SunOS Zone only, default: {})
  • data.monitoring_hostgroups (array) – Custom VM monitoring hostgroups (default: [])
  • data.monitoring_templates (array) – Custom VM monitoring templates (default: [])
  • data.mdata (object) – Customer metadata accessible from within the VM (key=value string pairs) (default: {})
Status Codes:

Note

The cpu_cap defines a percentage of a single compute node CPU that can be used by the VM. It is calculated automatically based on this formula: (vcpus * VMS_VM_CPU_BURST_RATIO * 100) + VMS_VM_CPU_BURST_DEFAULT, where VMS_VM_CPU_BURST_RATIO is by default 1.0 and VMS_VM_CPU_BURST_DEFAULT is by default 100 when vcpus > 1 and 50 when vcpus == 1.

PUT /vm/(hostname_or_uuid)/define
DC-bound?:
Permissions:
Asynchronous?:
Parameters:
  • hostname_or_uuid (string) – required - Server hostname or uuid
  • data.alias (string) – Short server name
  • data.template (string) – VM template name
  • data.vcpus (integer) – Number of virtual CPUs inside VM (1 - 1024); This number is used to calculate an internal compute node CPU limit for the VM (cpu_cap). When the VMS_VM_CPU_CAP_REQUIRED DC setting is disabled, then the vcpus value can be 0, which will remove the compute node CPU limit entirely (SunOS and LX Zone only)
  • data.ram (integer) – Size of RAM inside VM (1 - 1048576 MB)
  • data.note (string) – Text note visible to every user with access to this VM
  • data.owner (string) – User that owns the VM
  • data.node (string) – Name of the host system
  • data.tags (array) – Custom VM tags
  • data.monitored (boolean) – Enable VM synchronization with monitoring system
  • data.monitored_internal – Enable VM synchronization with internal monitoring system (requires SuperAdmin permission)
  • data.installed (boolean) – Mark the server as installed
  • data.snapshot_limit_manual (integer) – Maximum number of manual snapshots for this VM
  • data.snapshot_size_percent_limit – Maximum size of all snapshots for this VM relative to size of all defined VM disks. Ignored if snapshot_size_limit is defined
  • data.snapshot_size_limit (integer) – Maximum absolute size of all snapshots for this VM in megabytes
  • data.zpool (string) – The zpool used for the VM zone
  • data.cpu_shares (integer) – Number of VM’s CPU shares relative to other VMs (requires SuperAdmin permission)
  • data.zfs_io_priority (integer) – IO throttle priority relative to other VMs (requires SuperAdmin permission)
  • data.cpu_type (string) – KVM only; Type of the virtual CPU exposed to the VM. One of qemu64, host
  • data.vga (string) – KVM only; VGA emulation driver. One of std, cirrus, vmware
  • data.bootrom (string) – BHYVE only; Default VM boot firmware. One of bios, uefi (default: bios). Only uefi mode supports VNC.
  • data.dns_domain (string) – Search domain set in /etc/hosts (SunOS Zone only)
  • data.routes (object) – Key-value object that maps destinations to gateways. Items will be set as static routes in the OS (SunOS Zone only)
  • data.monitoring_hostgroups (array) – Custom VM monitoring hostgroups
  • data.monitoring_templates (array) – Custom VM monitoring templates
  • data.mdata (object) – Customer metadata accessible from within the VM (key=value string pairs)
Status Codes:
DELETE /vm/(hostname_or_uuid)/define
DC-bound?:
Permissions:
Asynchronous?:
Parameters:
  • hostname_or_uuid (string) – required - Server hostname or uuid
Status Codes:

es example:

es create /vm/example.cust.erigones.com/define -alias example -vcpus 1 -ram 1024 -ostype 1

{
    "url": "https://my.erigones.com/api/vm/example.cust.erigones.com/define/",
    "status": 201,
    "method": "POST",
    "text": {
        "status": "SUCCESS",
        "result": {
            "node": null,
            "ram": 1024,
            "hostname": "example.cust.erigones.com",
            "owner": "user@example.com",
            "alias": "example",
            "vcpus": 1,
            "template": null,
            "ostype": "1"
        },
        "task_id": "0-6a11849b-71fc-44b9-d31d"
    }
}

/vm/(hostname_or_uuid)/define/disk

api.vm.define.views.vm_define_disk_list(*args, **kwargs)

List (GET) VM disk definitions.

GET /vm/(hostname_or_uuid)/define/disk
DC-bound?:
Permissions:
Asynchronous?:
Parameters:
  • hostname_or_uuid (string) – required - Server hostname or uuid
  • data.active (boolean) – Display currently active VM disk definitions on compute node (default: false)
Status Codes:

es example:

es get /vm/example.cust.erigones.com/define/disk

{
    "url": "https://my.erigones.com/api/vm/example.cust.erigones.com/define/disk/",
    "status": 200,
    "method": "GET",
    "text": {
        "status": "SUCCESS",
        "result": [
            {
                "compression": "off",
                "image": "centos-6.4",
                "boot": true,
                "zpool": "zones",
                "model": "virtio",
                "size": 51200
            }
        ],
        "task_id": "0-6f75849b-1907-42a7-888f"
    }
}

/vm/(hostname_or_uuid)/define/disk/(disk_id)

api.vm.define.views.vm_define_disk(*args, **kwargs)

Show (GET), create (POST), change (PUT) or delete (DELETE) a VM disk definition.

GET /vm/(hostname_or_uuid)/define/disk/(disk_id)
DC-bound?:
Permissions:
Asynchronous?:
Parameters:
  • hostname_or_uuid (string) – required - Server hostname or uuid
  • disk_id (integer) – required - Disk number/ID (1 - 2)
  • data.active (boolean) – Display currently active VM disk definition on compute node (default: false)
  • data.diff (boolean) – Display differences between active VM definition on compute node and current configuration (default: false)
Status Codes:
POST /vm/(hostname_or_uuid)/define/disk/(disk_id)
DC-bound?:
Permissions:
Asynchronous?:
Parameters:
  • hostname_or_uuid (string) – required - Server hostname or uuid
  • disk_id (integer) – required - Disk number/ID (1 - 2)
  • data.size (integer) – required (if not specified in image) - Disk size (1 - 268435456 MB)
  • data.image (string) – required (if size is not specified) - Disk image name
  • data.model (string) – Disk driver. One of virtio, ide, scsi (default: virtio)
  • data.block_size (integer) – Block size for this disk (default: depends on OS Type)
  • data.compression (string) – Disk compression algorithm. One of off, lzjb, gzip, gzip-N, zle, lz4 (default: off)
  • data.zpool (string) – The zpool in which to create the disk (default: vm.zpool [zones])
  • data.boot (boolean) – Whether this disk should be bootable (default: true for first disk, otherwise false)
  • data.refreservation (integer) – Minimum amount of space in MB reserved for this disk (KVM only, default: size)
  • data.image_tags_inherit (boolean) – Whether to update VM tags from image tags (default: true)
Status Codes:
PUT /vm/(hostname_or_uuid)/define/disk/(disk_id)
DC-bound?:
Permissions:
Asynchronous?:
Parameters:
  • hostname_or_uuid (string) – required - Server hostname or uuid
  • disk_id (integer) – required - Disk number/ID (1 - 2)
  • data.size (integer) – Disk size (1 - 268435456 MB)
  • data.model (string) – Disk driver. One of virtio, ide, scsi
  • data.block_size (integer) – Block size for this disk
  • data.compression (string) – Disk compression algorithm. One of off, lzjb, gzip, gzip-N, zle, lz4
  • data.zpool (string) – The zpool in which to create the disk
  • data.boot (boolean) – Whether this disk should be bootable
  • data.refreservation (integer) – Minimum amount of space in MB reserved for this disk (KVM only)
  • data.image_tags_inherit (boolean) – Whether to update VM tags from image tags (default: true)
Status Codes:
DELETE /vm/(hostname_or_uuid)/define/disk/(disk_id)
DC-bound?:
Permissions:
Asynchronous?:
Parameters:
  • hostname_or_uuid (string) – required - Server hostname or uuid
  • disk_id (integer) – required - Disk number/ID (1 - 2)
  • data.image_tags_inherit (boolean) – Whether to update VM tags from image tags (default: true)
Status Codes:

es example:

es create /vm/example.cust.erigones.com/define/disk/1 -size 51200 -image centos-6.4 -boot true

{
    "url": "https://my.erigones.com/api/vm/example.cust.erigones.com/define/disk/1/",
    "status": 201,
    "method": "POST",
    "text": {
        "status": "SUCCESS",
        "result": {
            "compression": "off",
            "image": "centos-6.4",
            "boot": true,
            "zpool": "zones",
            "model": "virtio",
            "size": 51200
        },
        "task_id": "0-6f75849b-fd32-4d02-a08a"
    }
}

/vm/(hostname_or_uuid)/define/nic

api.vm.define.views.vm_define_nic_list(*args, **kwargs)

List (GET) VM NIC definitions.

GET /vm/(hostname_or_uuid)/define/nic
DC-bound?:
Permissions:
Asynchronous?:
Parameters:
  • hostname_or_uuid (string) – required - Server hostname or uuid
  • data.active (boolean) – Display currently active VM NIC definitions on compute node (default: false)
Status Codes:

es example:

es get /vm/example.cust.erigones.com/define/nic

{
    "url": "https://my.erigones.com/api/vm/example.cust.erigones.com/define/nic/",
    "status": 200,
    "method": "GET",
    "text": {
        "status": "SUCCESS",
        "result": [
            {
                "ip": "46.229.234.100",
                "nic_tag": "external",
                "netmask": "255.255.255.0",
                "dns": true,
                "net": "external",
                "model": "virtio",
                "gateway": "46.229.234.1",
                "vlan_id": 0
            }
        ],
        "task_id": "0-6f75849b-fded-477d-b6de"
    }
}

/vm/(hostname_or_uuid)/define/nic/(nic_id)

api.vm.define.views.vm_define_nic(*args, **kwargs)

Show (GET), create (POST), change (PUT) or delete (DELETE) a VM NIC definition.

GET /vm/(hostname_or_uuid)/define/nic/(nic_id)
DC-bound?:
Permissions:
Asynchronous?:
Parameters:
  • hostname_or_uuid (string) – required - Server hostname or uuid
  • nic_id (integer) – required - NIC number/ID (1 - 16)
  • data.active (boolean) – Display currently active VM NIC definition on compute node (default: false)
  • data.diff (boolean) – Display differences between active VM definition on compute node and current configuration (default: false)
Status Codes:
POST /vm/(hostname_or_uuid)/define/nic/(nic_id)
DC-bound?:
Permissions:
Asynchronous?:
Parameters:
  • hostname_or_uuid (string) – required - Server hostname or uuid
  • nic_id (integer) – required - NIC number/ID (1 - 16)
  • data.net (string) – required - Name of a virtual network
  • data.ip (string) – Virtual NIC IPv4 address. Must be part of net (default: auto select)
  • data.model (string) – Virtual NIC Model. One of virtio, e1000, rtl8139 (default: virtio); Bhyve has only virtio model
  • data.dns (boolean) – Create a DNS A record for VM’s FQDN? (default: true for first NIC, otherwise false)
  • data.use_net_dns (boolean) – Inherit DNS resolvers from network’s resolvers setting (default: false)
  • data.mac (string) – Virtual NIC MAC address (default: auto-generated)
  • data.primary (boolean) – Use this NICs gateway as VM default gateway (default: true for first NIC, otherwise false)
  • data.allow_dhcp_spoofing (boolean) – Allow packets required for DHCP server (requires SuperAdmin permission) (default: false)
  • data.allow_ip_spoofing (boolean) – Allow sending and receiving packets for IP addresses other than specified in ip (requires SuperAdmin permission) (default: false)
  • data.allow_mac_spoofing (boolean) – Allow sending packets with MAC addresses other than specified in mac (requires SuperAdmin permission) (default: false)
  • data.allow_restricted_traffic (boolean) – Allow sending packets that are not IPv4, IPv6, or ARP (requires SuperAdmin permission) (default: false)
  • data.allow_unfiltered_promisc (boolean) – Allow VM to have multiple MAC addresses. Use with caution! (requires SuperAdmin permission) (default: false)
  • data.allowed_ips (array) – List of additional IP addresses that can be used by this VM’s NIC and also by other VMs. Useful for floating/shared IPs (default: [])
  • data.monitoring (boolean) – Use this NIC’s IP address for external monitoring (default: true for first NIC, otherwise false)
  • data.set_gateway (boolean) – Whether to set gateway from network (data.net) settings (default: true)
Status Codes:
PUT /vm/(hostname_or_uuid)/define/nic/(nic_id)
DC-bound?:
Permissions:
Asynchronous?:
Parameters:
  • hostname_or_uuid (string) – required - Server hostname or uuid
  • nic_id (integer) – required - NIC number/ID (1 - 16)
  • data.net (string) – Name of a virtual network
  • data.ip (string) – Virtual NIC IPv4 address
  • data.model (string) – Virtual NIC Model. One of virtio, e1000, rtl8139. Bhyve has only virtio model
  • data.dns (boolean) – Create a DNS A record for VM’s FQDN?
  • data.use_net_dns (boolean) – Inherit DNS resolvers from network’s resolvers setting
  • data.mac (string) – Virtual NIC MAC address
  • data.primary (boolean) – Use this NICs gateway as VM default gateway
  • data.allow_dhcp_spoofing (boolean) – Allow packets required for DHCP server (requires SuperAdmin permission)
  • data.allow_ip_spoofing (boolean) – Allow sending and receiving packets for IP addresses other than specified in ip (requires SuperAdmin permission)
  • data.allow_mac_spoofing (boolean) – Allow sending packets with MAC addresses other than specified in mac (requires SuperAdmin permission)
  • data.allow_restricted_traffic (boolean) – Allow sending packets that are not IPv4, IPv6, or ARP (requires SuperAdmin permission)
  • data.allow_unfiltered_promisc (boolean) – Allow VM to have multiple MAC addresses. Use with caution! (requires SuperAdmin permission)
  • data.allowed_ips (array) – List of additional IP addresses that can be used by this VM’s NIC and also by other VMs. Useful for floating/shared IPs
  • data.monitoring (boolean) – Use this NIC’s IP address for external monitoring
  • data.set_gateway (boolean) – Whether to set gateway from network (data.net) settings
Status Codes:
DELETE /vm/(hostname_or_uuid)/define/nic/(nic_id)
DC-bound?:
Permissions:
Asynchronous?:
Parameters:
  • hostname_or_uuid (string) – required - Server hostname or uuid
  • nic_id (integer) – required - NIC number/ID (1 - 16)
Status Codes:

es example:

es create /vm/example.cust.erigones.com/define/nic/1 -net external

{
    "url": "https://my.erigones.com/api/vm/example.cust.erigones.com/define/nic/1/",
    "status": 201,
    "method": "POST",
    "text": {
        "status": "SUCCESS",
        "result": {
            "ip": "46.229.234.100",
            "nic_tag": "external",
            "netmask": "255.255.255.0",
            "dns": true,
            "net": "external",
            "model": "virtio",
            "gateway": "46.229.234.1",
            "vlan_id": 0
        },
        "task_id": "0-6f75849b-4b46-453f-acee"
    }
}

/vm/(hostname_or_uuid)/define/revert

api.vm.define.views.vm_define_revert(*args, **kwargs)

Revert (PUT) whole VM definition (including disks and nics) to currently active VM definition on compute node.

PUT /vm/(hostname_or_uuid)/define/revert

Warning

The DNS settings for server’s hostname and IP addresses won’t be reverted.

DC-bound?:
Permissions:
Asynchronous?:
Parameters:
  • hostname_or_uuid (string) – required - Server hostname or uuid
Status Codes: