Skip to content

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