Overview
Want to deploy a bunch of Virtual Canaries and have them pre-configured during the deployment on VMware vSphere/ESXi? We can do this using Advanced Configuration Parameters available on these platforms. These Advanced Configuration Parameters only affect the initial startup configuration of your VMware Canary before it is registered with the console. (This is available in VMware Canaries from v3.2.8 and onwards.)
Reach out to support@canary.tools to enable the 3.2.8 VMware image on your Console.
Launching a VM with guestinfo parameter Settings
The guestinfo settings must be supplied to the VM before it is launched the first time, these values cannot be applied after the initial power up. (We have tested using settings using vSphere 8.0.2 and ESXi 7.0.3)
The guide for using ESXi can be found here.
Setting Advanced Configuration Parameters in vSphere
Follow the steps in How do I deploy a Virtual Canary on VMware vSphere to deploy the OVA to vSphere to grab the OVA for deployment,
Note: Do not power on your Canary before configuring the guestinfo parameters.
After the OVA/OVF Template has been deployed it is now time to configure the guestinfo parameters for the instance that will allow it to be customised at startup.
- Edit the settings of your newly deployed virtual Canary.
- Select the Advanced Parameters tab
- Add the required parameters for your virtual Canary, we cover the available parameters below.
- Once all of the desired parameters have been added select OK
- Power on your Canary
guestinfo Parameters
By launching a VM with its guestinfo parameters defined as per the table below, your virtual Canary will apply the settings at boot.
|
Guestinfo Key |
Configuration Target |
Structure |
|
guestinfo.network |
Canary network settings |
Base64-encoded JSON structure, see Network Configuration |
|
guestinfo.initial_profile |
Sets the Canary’s profile type |
Profile label, see Profile Configuration |
|
guestinfo.initial_settings |
Sets additional settings for your Canary |
Base64-encoded JSON structure, see Settings Configuration |
| guestinfo.autocommission_token | Sets the Auto-commission Token to enrol your Canary with the console | Auto-commission Token |
Network Configuration
The VM’s network settings are supplied by the guestinfo.network configuration item. This is a Base64-encoded JSON structure. If the setting is not supplied, the bird will rely on DHCP. To create this guestinfo setting, follow these steps:
Step 1: Create a JSON representation of the network settings
{
"device.name": "WIN-INY-SRV-01",
"device.dhcp.enabled": false,
"device.ip_address": "192.168.5.206",
"device.netmask": "255.255.255.0",
"device.gw": "192.168.5.1",
"device.dns1": "192.168.5.1",
"device.dns2": "192.168.5.9"
}
All of the fields above are required, the settings are self-explanatory except for "device.name". This field will show up in your Canary Console and can be used to identify the bird.
Step 2: Encode the JSON structure with Base64
Pass the above JSON string through a Base64 encoder to yield a string such as this:
ewogICJkZXZpY2UubmFtZSI6ICJXSU4tSU5ZLVNSVi0wMSIsCiAgImRldmljZS5kaGNwLmVuYWJsZWQiOiBmY
WxzZSwKICAiZGV2aWNlLmlwX2FkZHJlc3MiOiAiMTkyLjE2OC41LjIwNiIsCiAgImRldmljZS5uZXRtYXNrIj
ogIjI1NS4yNTUuMjU1LjAiLAogICJkZXZpY2UuZ3ciOiAiMTkyLjE2OC41LjEiLAogICJkZXZpY2UuZG5zMSI
6ICIxOTIuMTY4LjUuMSIsCiAgImRldmljZS5kbnMyIjogIjE5Mi4xNjguNS45Igp9
Note: Base64 encoding can include padding "=" characters at the end. Make sure to include them.
Step 3: Use the Base64 string
Insert the Base64 string from Step 2 as the guestinfo.network configuration item.
Profile Configuration
Canaries have pre-built profiles. By supplying the optional guestinfo.initial_profile, one can have the Canary launch and run one of these pre-built profiles. Profile names are simple strings, such as “win-2019-fileshare”, “cisco-router”, or “jira”.
If no profile is configured explicitly with guestinfo.initial_profile, then the default “win-2019-fileshare” profile is used.
The currently supported list of profiles names are:
| Name | Description |
| bare | Bare Canary (no services) |
| merry-christmas | Christmas Tree (all services) |
| win-2019-fileshare | Windows Server 2019 Office Fileshare |
| win-2016-fileshare | Windows Server 2016 Office Fileshare |
| win-2012-fileshare | Windows Server 2012 Office Fileshare |
| win-2008-fileshare | Windows Server 2008 Office Fileshare |
| win-2003-fileshare | Windows Server 2003 Office Fileshare |
| win-2000-fileshare | Windows Server 2000 Office Fileshare |
| winxp-fileshare | Windows XP Desktop Fileshare |
| win7-fileshare | Windows 7 Desktop Fileshare |
| win8-fileshare | Windows 8 Desktop Fileshare |
| win10-fileshare | Windows 10 Desktop Fileshare |
| win-2019-dc | Microsoft AD Domain Controller 2019 |
| win-2016-dc | Microsoft AD Domain Controller 2016 |
| win-2012-dc | Microsoft AD Domain Controller 2012 |
| sharepoint | MS Sharepoint 2010 |
| iis7 | IIS 7 |
| iis10 | IIS 10 |
| linux-std | Standard Linux Server |
| linux-db | Linux Database |
| linux-proxy | Linux Proxy |
| centos7basic | CentOS 7 Server |
| oracle-linux-6 | Oracle Enterprise Linux 6 |
| oracle-linux-7 | Oracle Enterprise Linux 7 |
| oracle-linux-8 | Oracle Enterprise Linux 8 |
| osx-fileshare | Mac OS X Fileshare |
| dell-switch | Dell Switch |
| dell-idrac | Integrated Dell Remote Access Controller |
| cisco-router | Cisco Router |
| cisco-voip | Cisco VoIP Phone 7975G |
| cisco-vpn | Cisco SSL VPN |
| sonicwall-firewall | SonicWALL NSA 220 Firewall Appliance |
| citrix-gateway | Citrix Gateway |
| paloalto-firewall | Palo Alto Firewall |
| f5-gateway | F5 BIG-IP Edge Gateway |
| checkpoint-mobile-vpn | Check Point Mobile VPN |
| pulsevpn | Pulse VPN |
| juniper-srx | Juniper SRX 550 |
| diskstation-nas | Synology DiskStation 5 NAS |
| diskstation6-nas | Synology DiskStation 6.2 NAS |
| diskstation7-nas | Synology DiskStation 7.1 NAS |
| vmware-server | VMware ESXi Server |
| vmware-server-7 | VMware ESXi 7 Server |
| vmware-vcenter-7 | VMware vCenter 7 Server |
| hpilo | HP iLO Server |
| joomla | Joomla Server |
| cups | CUPS Service |
| jboss | JBoss Login |
| zos-mainframe | IBM z/OS Mainframe |
| canon-image-runner-2525-multifunction-printer | Canon ImageRUNNER 2525 |
| splunk-linux | Splunk Linux Server |
| splunk-windows | Splunk Windows Server |
| owa | Outlook Web Access |
| sap-netweaver | SAP NetWeaver Windows Server |
| solarwinds | Solarwinds |
| kibana | Kibana Server |
| jira | Jira |
| sophos-userportal | Sophos User Portal |
| sophos-webconsole | Sophos Web Console |
| jenkins | Jenkins Login |
| rockwell-1769-L23E-QB1 | Rockwell Automation PLC |
| scada-siemens-simatic-300 | Siemens Simatic 300 PLC |
| hirschmann-RS20 | Hirschmann RS20 Industrial Switch |
Settings Configuration
Canaries are highly configurable. In addition to the profile settings shown above, individual services and be tweaked and configured through a JSON settings object. This is an advanced usage, and atypical.
Where a profile has been set (e.g. "cisco-router"), it can be further configured through the guestinfo.initial_settings parameter which holds settings to be applied after the profile. An approach is to pick a pre-built profile, then use guestinfo.initial_settings to further tweak profiles to suit local conditions.
A sample of possible configuration values is available here.
The guestinfo.initial_settings configuration item is a Base64-encoded JSON structure. To create this guestinfo setting, follow these steps:
Step 1: Create a JSON representation of the settings
{
"ftp.banner": "Cisco FTP server ready",
"ftp.enabled": true,
"ftp.port": 21
}
These settings are applied after the profile is applied (bearing in mind the default profile is "win-2019-fileshare"). This approach means you can override settings in the pre-built profiles. You can turn on services that are not enabled in a profile, and conversely disable services in pre-built profiles.
Step 2: Encode the JSON structure with Base64
Pass the JSON string from Step 1 through a Base64 encoder to yield an encoded string such as:
eyJmdHAuYmFubmVyIjogIkNpc2NvIEZUUCBzZXJ2ZXIgcmVhZHkiLCJmdHAuZW5hYmxlZCI6IHRydWUsImZ0
cC5wb3J0IjogMjF9
Note: Base64 encoding can include padding "=" characters at the end. Make sure to include them.
Step 3: Use the Base64 string
Insert the string from Step 2 as the guestinfo.initial_settings configuration item.
Auto-Commission Token Configuration
Canaries can be automatically enrolled with the console, by supplying the guestinfo.autocommission_token. When the bird is powered on it will automatically be added to the console and placed into the correct Flock without any intervention required.
The token is a random string. A sample value of the token would look like this:
1f411551b47df4c0d5eb
This token is then added to the guestinfo.autocommission_token parameter.
See the Auto Commission page for more information on how to enable this feature.