In 11.1 and following there are multiple ways for a client to select its relay, i'll explain which ones, what are their advantages and disadvantages and how to update this config on existing agent or new ones.
You might want to read Andrew's great blog article to understand how a relay works prior to reading this document.
1- Where is this configured on my agents?
Select a device in the "Search" node or in the "Device Topology" node or in the "Device Groups" node then click on "Agent Configuration" and then on "Communication":
You can see that there are two different ways of selecting a relay:
A- Static Relay: clients will always use the selected relay and will not attempt communication with another relay. This is typically used for smaller LAN environments that do not use many relays.
The problem with this configuration is that if your relay gets down, the clients will not be able to receive any operational rule, package etc until the relay is back up.
This configuration must be used on relays that are directly under the master as you do not want a master to be dynamically selected by relays.
To configure it, simply set:
- your relay's hostname or its ip address in the field "Parent Name".
- your relay's agent port in the field "Parent Port", this is usually "1610".
B- Auto-select Relay: clients will attempt to find a relay using one or more of the selected methods in the order defined below: if a method cannot find the relay, it will return and the next method in the list will be tried:
In this example we'll test the "DHCP Extended Option" mechanism first. If it fails to select a relay with this first mechanism it'll try to select one using the mechanism "Relay list Server" then it'll try the "Backup Relay" mechanism if the second mechanism failed too.
2- Configuring auto-selection:
A- DHCP Extended Option:
This option will allow your device to get its relay from an extended option set on your DHCP server.
IMHO it's the best option to choose as:
- it can easily be set and updated if the server's hostname changes
- there no need to create one entry per subnet nor to calculate subnets (when you have non default subnet masks) as you should do for lists of relays
- devices don't have to be able to contact the master as they should for a list of relays
Samuel has made a great how-to on how to set this option on the DHCP server. Note that we chose the option 222 but you can choose any option number you want. Don't forget to change "222" by the option you chose here when setting the option as in the next screenshot.
Once this is configured on your DHCP servers you should set this on your devices' "Communication" sub-node:
B- Relay List Server:
Another common primary method is the Relay List which will be hosted on the master server and allows mapping of IP subnets to relays. To set this you should first identify every subnet where there are devices supposed to attach to a specific relay and set them either:
- in the console in "Global Settings" > "Relay List":
- when adding the mechanism in the "Communication" node:
In this example you'll see that:
- you must set an entry for each subnet that'll rely on a relay instead of beeing able to set multiple subnets for an entry. I have created an idea to change this as this is a big disadvantage.
- you can set multiple relays for the same subnet and set various priorities to select one or another first.
An idea was created to try to select relays with a lower priority prior to trying the next mechanism if the relay fails.
- one entry must be set by subnet
- the client must be able to contact the master to be able to check the relay list
- beware of specific masks such as 10.5.158.143/255.255.252.0 as your client will not be able to select a relay if you set 10.5.158.0 as the relay's subnet. Calculate it and set the according subnet. Here it'll be 10.5.156.0.
C- Backup Relay:
These can be well complemented by the Static Relay or Backup Relay as secondary methods (i.e. if DHCP and Relay List were not able to find a suitable relay, a list of backup or a static relay will be used).
Backup Relay is also well suited for agents that connect through the internet and do not have access to DHCP or the master server. In this case, one or more internet facing relays can be added to the backup relays.
Most users will set this mechanism as the second one. You might want to set your master or a super relay by area as a backup relay (i'd recommend to do so).
Note that this option also allows you to run a script when one of the backup relays listed will be selected.
- you cannot set priorities, the server that'll answer the fastest will be selected but normally the closest relay will be selected so i'm not sure it's really a disadvantage
- you will have to create multiple rollout configurations if you want to set a backup relay specific to where the device is in the world as an example
D- Static Relay:
This option can also be set as an auto-selection mechanism. It can typically be used in an environment where there's only one relay or so where the master will be the backup relay (see C-):
Auto-discovery lets client agents perform a network scan on either a pre-defined range of IP addresses or a number of neighbours surrounding their IP address.
This has to be used cautiously as it creates network traffic and requires good configuration so agents efficiently find their relays. You'll find more information about the AutoDiscovery settings the documentation BMCFPAssetCore_ParameterReference.pdf p.45.
Prerequisite: the module "autodiscovery must be loaded: if "AutoDiscovery" doesn't appear in the sub-node "Module Configuration" then select the tab "Configuration" and right click on the window, select "Load Modules" and select "AutoDiscovery":
We usually recommend to set a list of relays instead of setting ip ranges if the user doesn't need the autodiscovery module for something else in asset core:
- this can be usefull on networks where you don't really know which devices exist and in which subnets they are
- setting auto-discovery could also help you automatically push agents on existing/new devices
- This mechanism is deprecated as the previously decribed mechanisms should be more efficient.
F- Custom Script:
Custom Script is used when none of the built-in methods mentioned above fits the environment and a customised script is available to handle relay discovery.
I would not recommend this method as the first methods described should satisfy most needs. It was usefull before we implemented A- and B- and is now mostly deprecated.
The following will also apply to the scripts you can set on the "Backup Relay" mechanism.
You can either deploy the script on every device you want to use it on or set it on a webserver as described in the tooltip:
- It might be interesting to use the custom script to select a backup relay reguarding of the device's location instead of selecting any relay from the "Backup Relay" list. This will allow you to use a universal rollout instead of setting one up for every backup relay in this case.
- this script will be written in chilli. You'll find informations about Chilli in the documentation BMCFPAssetCore_ChilliReference.pdf that is only avalaible in english
- most users will copy the script on every device as a postinstall file in their rollout configuration(s) and make their script look in a relay_list.ini to select their relay. This .ini will be available on every device or on a web server.
3- How to deploy a (new) config for the relay module:
I have splitted this part so the document length doesn't frighten people. You will find information about this in this document.
- if you're unsure of the port your devices' relays are using to communicate with other devices simply select your relays then go in their configuration subnodes:
- if a device's relay is unavailable, you'll still be able to take control or use direct access as long as the ip is correct in the database and as long as a tunnel through the relay is not needed. If it's not you can trick the system by setting the ip yourself in the console. (check that)
- i made a document that'll help you understand why aren't your windows devices connecting to their relay and i'm sure there was a document on how to troubleshoot the same thing on linux/mac clients but i can't find it...
- John made a great document on how to do load balancing via relay lists.
Note: Please consider marking this post as correct or recommandable if you found it usefull.