Server event hooks
All server hook points have access to the full server object. The object may differ between servers, so it's wise to check a property exists before trying to access it.
Example server object
{
"id": 499,
"ownerId": 1,
"hypervisorId": 26,
"name": "My Server 1",
"hostname": null,
"commissionStatus": 3,
"uuid": "c2ee9c72-6245-4f11-a0ae-e6c847110ff1",
"state": "complete",
"migrateLevel": 0,
"deleteLevel": 0,
"configLevel": 0,
"backupLevel": 0,
"rebuild": false,
"suspended": false,
"protected": false,
"buildFailed": false,
"primaryNetworkDhcp4": false,
"primaryNetworkDhcp6": false,
"built": "2022-06-25T22:00:39+00:00",
"created": "2022-06-25T21:59:53+00:00",
"updated": "2022-07-18T14:33:05+00:00",
"traffic": {
"public": {
"countMethod": 1,
"currentPeriod": {
"start": "2022-06-25T00:00:00.000000Z",
"end": "2022-07-24T23:59:59.999999Z",
"limit": 10
}
}
},
"settings": {
"osTemplateInstall": true,
"osTemplateInstallId": 3,
"encryptedPassword": "eyJpdiI6IkVXM3ZVTWlObTRaQ1Nvb3RzclY3dlE9PSIsInZhbHVlIjoiNFBRdU04ZWtVOGloVFpYQXo5NHlEdmdrdjlxZGhzQU9xbFozY2V0VmN0Yz0iLCJtYWMiOiJmZTc5NDYzMjZhMDM4ZTBjOWM3ZGU3MDQ3YzJhMzU0ZGEyNTA4MTEyMmU5YTlmYmIzMTEyZjc3MmFiYzFjNjJmIiwidGFnIjoiIn0=",
"backupPlan": 1,
"uefi": false,
"cloudInit": true,
"cloudInitType": 1,
"config": {
"cloud.init": {
"on.all": {
"user.data": {
"package_update": true,
"package_upgrade": true,
"mounts": [
[
"vdb",
"/data1",
"auto",
"defaults,nofail",
"0",
"0"
],
[
"vdc",
"/data2",
"auto",
"defaults,nofail",
"0",
"0"
]
]
}
},
"on.password": {
"user.data": []
},
"on.sshkey": {
"user.data": []
},
"on.network": [],
"on.network.libvirtrouted": []
}
},
"userConfig": [],
"bootOrder": [
"hd",
"cdrom"
],
"resources": {
"memory": 1024,
"storage": 10,
"traffic": 10,
"cpuCores": 1
}
},
"media": {
"isoMounted": false,
"isoName": "",
"isoFilename": "",
"isoUrl": "",
"isoDownload": false
},
"vnc": {
"ip": "10.0.0.10",
"encryptedPassword": "eyJpdiI6Imhtd1dGQlJWaDZvUXN5bkU0emRib2c9PSIsInZhbHVlIjoiS1Y5TzdqSEFCRmtqSjVaKzF4eEdldz09IiwibWFjIjoiNzNlZjJjYjMxNjAwYzNiYWE5MDRlMGU5MmJiN2ZiZGVkMWJlNTQyZmVlODA2ZjM4MTQwNjI0NTc4MjcyZjkxNyIsInRhZyI6IiJ9",
"port": 5906,
"enabled": false
},
"network": {
"interfaces": [
{
"order": 1,
"enabled": true,
"tag": 8527570150,
"name": "eth0",
"type": "public",
"driver": null,
"mac": "00:F5:5C:5E:26:76",
"ipv4ToMac": null,
"ipv6ToMac": null,
"inTrafficCount": true,
"outTrafficCount": false,
"inAverage": 0,
"inPeak": 0,
"inBurst": 0,
"outAverage": 0,
"outPeak": 0,
"outBurst": 0,
"ipFilter": true,
"ipFilterType": "4",
"portIsolated": true,
"ipv4_resolver_1": 1,
"ipv4_resolver_2": 2,
"ipv6_resolver_1": 1,
"ipv6_resolver_2": 2,
"networkProfile": 0,
"dhcpV4": 0,
"dhcpV6": 0,
"hypervisorNetwork": 1,
"hypervisorConnectivity": {
"id": 1,
"type": "simpleBridge",
"bridge": "br0",
"mtu": null,
"primary": true,
"default": true
},
"ipWhitelist": [],
"actions": [],
"ipv4": [
{
"id": 81,
"order": 1,
"enabled": true,
"address": "10.0.1.23",
"gateway": "10.0.1.1",
"netmask": "255.255.255.0",
"resolver1": "8.8.8.8",
"resolver2": "8.8.4.4",
"rdns": null,
"mac": null
}
],
"ipv6": []
}
],
"secondaryInterfaces": [
{
"order": 1,
"enabled": true,
"tag": 6384380578,
"name": "eth1",
"type": "private",
"driver": null,
"mac": "00:0C:F6:FB:59:AC",
"ipv4ToMac": null,
"ipv6ToMac": null,
"inTrafficCount": true,
"outTrafficCount": false,
"inAverage": 0,
"inPeak": 0,
"inBurst": 0,
"outAverage": 0,
"outPeak": 0,
"outBurst": 0,
"ipFilter": true,
"ipFilterType": "6",
"portIsolated": true,
"ipv4_resolver_1": 1,
"ipv4_resolver_2": 2,
"ipv6_resolver_1": 1,
"ipv6_resolver_2": 2,
"networkProfile": 0,
"dhcpV4": 0,
"dhcpV6": 0,
"hypervisorNetwork": 1,
"hypervisorConnectivity": {
"id": 1,
"type": "simpleBridge",
"bridge": "br0",
"mtu": null,
"primary": true,
"default": true
},
"ipWhitelist": [],
"actions": [],
"ipv4": [],
"ipv6": [
{
"id": 1906,
"order": 1,
"enabled": true,
"addresses": [
"2a0f:93c1:26:2fb:5::a"
],
"addressesDetailed": [
{
"address": "2a0f:93c1:26:2fb:5::a",
"rdns": null
}
],
"subnet": "2a0f:93c1:26:2fb:5::",
"cidr": 80,
"gateway": "2a0f:93c1:26::1",
"resolver1": "2001:4860:4860::8888",
"resolver2": "2001:4860:4860::8844"
}
]
}
]
},
"storage": [
{
"_id": 528,
"id": 1,
"cache": null,
"bus": null,
"capacity": 10,
"drive": "a",
"filesystem": null,
"iops": {
"read": null,
"write": null
},
"bytes": {
"read": null,
"write": null
},
"type": "qcow2",
"profile": 0,
"status": 3,
"enabled": true,
"primary": true,
"created": "2022-06-25T21:59:53+00:00",
"updated": "2022-07-04T17:27:36+00:00",
"name": "c2ee9c72-6245-4f11-a0ae-e6c847110ff1_1",
"filename": "c2ee9c72-6245-4f11-a0ae-e6c847110ff1_1.img",
"hypervisorStorageId": 11,
"local": true,
"locationType": "mountpoint",
"path": "/data1/disk1"
}
],
"hypervisor": {
"id": 26,
"ip": "10.0.0.10",
"hostname": null,
"maintenance": false,
"groupId": 1,
"backupStorageType": 2,
"defaultDiskType": "inherit",
"defaultDiskCacheType": "none",
"created": "2021-05-21T10:31:19+00:00",
"updated": "2022-05-23T08:12:39+00:00",
"name": "Test Hypervisor 1",
"dataDir": "/home/vf-data",
"encryptedToken": "eyJpdiI6InpvT0JaUWJyK3kxY3pXQ1VuYjM5dkE9PSIsInZhbHVlIjoialBiNnVxM1cvQncwSW42eHlPNEtxZzVyM2FhSzl6TEtiRXdYdFBmMnU1U2RqZmhEdktWVFJlbktPYU5RVnZ5MHBKWHNxNEhTeExxWThUZzl4V1dHc1hBMDVWNHAvNXp0T1lSYmowSHBPdnpGVDY1WFkxSUpmQWN2bEltT2hORU9hbnBlSDRDT1pkTTFBa2Z4TThOWmQ2cGo2QTh6clZsb2M4VDJ1Y2xhZXVUTzRybzIvai9IanI1bEZPU296T1REaHQvb1Jjc05zb21LVWZtYWdkT2ZXUnNFMkUrSm1pNGc3eTF4SHNyQUpiZGx3Tko5Mk9ZeG5Sc3VKOWpKVWxUTVp0enlrc3FkS0x0ZkU4R2w0UUJJbDdjbW9qbkpUc1YzeHoyWEJXTkJEcFdjUHUxSThWa2xhczhNMGhMbTZCaWVQZUNSNm51ZGQ3SFd5TEZGK3ZFZXV5YTVPS3FBZTFMRTIxYzdJand0ZnVlWU9BYzQvM20yQzdUODJKeVFQZEdpdzM0Q1NjQzFvNkRLZ05iUDZpOW5wRXU2L28zTXRhalQ1S1NLUURuK1Q1MTZHazR4Wk5Qc1d0Ym9WaWRSLzl5akFrTm5XaEVZSjcvN09tZW1wVVhHVkNZTGhCUHREbStCeVJ4Q3R4N3NGUXkySVNnU2R5cHMzK0ZmVjlOSDdUcjNnL3Q5bGZ3TTZjUGRkVStiN3ByTVZGWkVXRmFYRk8zVVpQOWdXT1hGVVJ0aGdQS25iYm5BNk1HNVNzSysweG0zVFZxWEIxMGJUN015Q1pNWlR5L0pkWk91ZkJmKzVNSkdpMlVKbWVlWHhMeEtlbGZYUkswSy9qVjhmc0Fzd2F3TFVoVkR1QUR1dmU0MC9CTVplbkM4QVhiUzBHOTNlZ0RDYXdmaTNkL1NFbVU9IiwibWFjIjoiNWIwNDZiNTAxMzE4YzY1YzlhZGU5YTIwOGYxODViMjgxN2Q1ZTI1NjM4ZjRiOTdmZjc3MjJkZDEyZDZlOGQ5ZCIsInRhZyI6IiJ9"
},
"owner": {
"id": 1,
"admin": true,
"extRelationId": null,
"name": "Harry Potter",
"email": "harry.potter@gmail.com",
"timezone": "Europe/London",
"suspended": false,
"twoFactorAuth": false,
"created": "2020-12-11T19:54:21+00:00",
"updated": "2022-07-12T13:32:03+00:00"
},
"sshKeys": [],
"xmlConfig": "<?xml version=\"1.0\"?>\n<!--\n ####### DO NOT DIRECTLY EDIT THIS CONFIGURATION #######\n Automatically generated by VirtFusion on Mon Jul 18 14:33:05 UTC 2022\n-->\n<domain type=\"kvm\">\n <name>c2ee9c72-6245-4f11-a0ae-e6c847110ff1</name>\n <uuid>c2ee9c72-6245-4f11-a0ae-e6c847110ff1</uuid>\n <memory unit=\"KiB\">1048576</memory>\n <currentMemory unit=\"KiB\">1048576</currentMemory>\n <!--\n ####### CPU #######\n-->\n <vcpu placement=\"static\" current=\"1\">128</vcpu>\n <cpu mode=\"host-model\"/>\n <!--\n # END\n-->\n <os>\n <type machine=\"pc\">hvm</type>\n <boot dev=\"hd\"/>\n <boot dev=\"cdrom\"/>\n </os>\n <clock offset=\"utc\">\n <timer name=\"rtc\" tickpolicy=\"catchup\"/>\n </clock>\n <devices>\n <memballoon model=\"virtio\">\n <stats period=\"5\"/>\n </memballoon>\n <console type=\"pty\">\n <target type=\"serial\"/>\n </console>\n <emulator>/usr/bin/qemu-system-x86_64</emulator>\n <graphics type=\"vnc\" port=\"5906\" passwd=\"9hMKuwTC\" listen=\"0.0.0.0\" autoport=\"no\"/>\n <!--\n ####### GUEST AGENT #######\n-->\n <channel type=\"unix\">\n <source mode=\"bind\"/>\n <target type=\"virtio\" name=\"org.qemu.guest_agent.0\"/>\n </channel>\n <!--\n # END\n-->\n <controller type=\"scsi\" model=\"virtio-scsi\"/>\n <!--\n ####### STORAGE #######\n-->\n <disk type=\"file\" device=\"disk\">\n <driver name=\"qemu\" type=\"qcow2\" cache=\"none\"/>\n <source file=\"/data1/disk1/c2ee9c72-6245-4f11-a0ae-e6c847110ff1_1.img\"/>\n <target dev=\"vda\" bus=\"virtio\"/>\n </disk>\n <!--\n # END\n-->\n <!--\n ####### CD MEDIA #######\n-->\n <disk type=\"file\" device=\"cdrom\">\n <target dev=\"sdy\" bus=\"sata\"/>\n <address type=\"drive\" target=\"0\" bus=\"0\" controller=\"0\"/>\n <readonly/>\n </disk>\n <!--\n # END\n-->\n <!--\n ####### NETWORK #######\n-->\n <interface type=\"bridge\">\n <model type=\"virtio\"/>\n <source bridge=\"br0\"/>\n <target dev=\"8527570150\"/>\n <mac address=\"00:F5:5C:5E:26:76\"/>\n <filterref filter=\"vf-server-8527570150\">\n <parameter name=\"IP\" value=\"10.0.1.23\"/>\n <parameter name=\"IP_MASK\" value=\"32\"/>\n </filterref>\n <port isolated=\"yes\"/>\n </interface>\n <interface type=\"bridge\">\n <model type=\"virtio\"/>\n <source bridge=\"br0\"/>\n <target dev=\"6384380578\"/>\n <mac address=\"00:0C:F6:FB:59:AC\"/>\n <filterref filter=\"vf-server-6384380578\">\n <parameter name=\"IPV6\" value=\"2a0f:93c1:26:2fb:5::\"/>\n <parameter name=\"IPV6_MASK\" value=\"80\"/>\n </filterref>\n <port isolated=\"yes\"/>\n </interface>\n <!--\n # END\n-->\n <input type=\"tablet\"/>\n <input type=\"mouse\"/>\n <video>\n <model type=\"vga\" vram=\"8192\" heads=\"1\">\n <acceleration accel3d=\"no\" accel2d=\"no\"/>\n </model>\n </video>\n </devices>\n <features>\n <acpi/>\n <apic/>\n <pae/>\n </features>\n <on_poweroff>destroy</on_poweroff>\n <on_reboot>restart</on_reboot>\n <on_crash>restart</on_crash>\n</domain>\n"
}
Example hook
All PHP based hook points must have an event($data) function and must NOT contain a closing tag (?>).
<?php
function event($data)
{
// Your code here...
}
It's always wise to check that the properties you require are within the data object before accessing them.
if (!property_exists($data, 'hypervisor')) return;
...
if (!property_exists($data, 'xmlConfig')) return;
Hook points
| Hook Name | Description | Since |
|---|---|---|
server-before-config-write | Triggered just before the server XML configuration is written to disk. | 1.7.2 |
server-after-config-write | Triggered just after the server XML configuration has been written to disk. | 1.7.2 |
server-before-boot | Triggered just before the server is booted. | 1.7.2 |
server-after-boot | Triggered just after the server has been booted. | 1.7.2 |
server-before-poweroff | Triggered just before the server is powered off. | 1.7.2 |
server-after-poweroff | Triggered just after the server has been powered off. | 1.7.2 |
server-before-shutdown | Triggered just before the server is shutdown. | 1.7.2 |
server-after-shutdown | Triggered just after the server has been shutdown. | 1.7.2 |
server-before-suspend | Triggered just before the server is suspended. | 1.7.2 |
server-after-suspend | Triggered just after the server has been suspended. | 1.7.2 |
server-before-unsuspend | Triggered just before the server is unsuspended. | 1.7.2 |
server-after-unsuspend | Triggered just after the server has been unsuspended. | 1.7.2 |
server-before-cloudinit-config | Triggered just before the cloud-init config is written to disk. | 1.7.2 |
server-after-cloudinit-config | Triggered just after the cloud-init config has been written to disk. | 1.7.2 |
server-before-cloudinit-attach | Triggered just before the cloud-init drive is attached. | 1.7.2 |
server-after-cloudinit-attach | Triggered just after the cloud-init drive has been attached. | 1.7.2 |
server-before-traffic-throttle-primary | Triggered just before the server primary interface is throttled. | 1.7.2 |
server-after-traffic-throttle-primary | Triggered just after the server primary interface has been throttled. | 1.7.2 |
server-before-traffic-unthrottle-primary | Triggered just before the server primary interface is unthrottled. | 1.7.2 |
server-after-traffic-unthrottle-primary | Triggered just after the server primary interface has been unthrottled. | 1.7.2 |
server-before-insert-iso | Triggered just before an ISO is inserted. | 1.7.2 |
server-after-insert-iso | Triggered just after an ISO has been inserted. | 1.7.2 |
server-before-eject-iso | Triggered just before an ISO is ejected. | 1.7.2 |
server-after-eject-iso | Triggered just after an ISO has been ejected. | 1.7.2 |
server-before-enable-vnc | Triggered just before VNC is enabled. | 1.7.2 |
server-after-enable-vnc | Triggered just after VNC has been enabled. | 1.7.2 |
server-before-disable-vnc | Triggered just before VNC is disabled. | 1.7.2 |
server-after-disable-vnc | Triggered just after VNC has been disabled. | 1.7.2 |
server-before-disk-create-primary | Triggered just before the primary disk is created (build/rebuild). | 1.7.2 |
server-after-disk-create-primary | Triggered just after the primary disk has been created (build/rebuild). | 1.7.2 |
server-before-reset-password | Triggered just before the password is reset. | 1.7.2 |
server-after-reset-password | Triggered just after the password has been reset. | 1.7.2 |
server-before-destroy | Triggered just before the server is destroyed. | 1.7.2 |
server-after-destroy | Triggered just after the server has been destroyed. | 1.7.2 |