Autoprovision processor (ap)
Description
Autoprovision processor. Handles requests from devices arriving over TFTP and PNP protocols.
Made redundant and scaled in Active-Active mode.
When a TFTP request arrives, it first looks for a ready file in the :SYNC/common/autoprovision/configurations directory (management is also available via the master domain REST API /rest/v1/fs/targets/ap_configurations).
If the file is not found, it tries to find a template, fill it, and return it.
1. The MAC address is extracted from the file name.
2. The sipuser account is found by MAC (field `opts.ap_devices.mac` or `opts.ap_mac_address`). The search is performed in all domains.
3. The template name mask is found by the file name in `MasterDomain.settings.ap_options.masks`. The mask may contain a type; in that case, when searching for the template, it acts as the file’s final extension.
4. The device model is determined from the account (field `opts.ap_devices.device_model` or `opts.ap_device_model`).
5. Based on the type from the template name mask and the detected device model, the autoprovision settings template is searched for (placed in the :SYNC/common/autoprovision/templates directory and available via REST API /rest/v1/fs/targets/ap_templates).
6. The template is treated as a text file or XML. The template is filled with values from the sipuser account, domain constants (`Domain.settings.ap_constants`), master domain constants (`MasterDomain.settings.ap_constants`), and site constants (`:SYNC/common/autoprovision/constants/<SiteName>.cfg`), The [blf] section is filled by repeated template substitution for BLF, taken for the detected device model and filled based on the list (field `opts.ap_devices.blf or ext.ap_blf`).
7. The template is supplemented or adjusted with individual settings (field `opts.ap_devices.override` or `ext.ap_override`). The result is returned to the device for autoconfiguration.
.
If firmware and other files not dependent on the MAC address must be downloaded, they should be placed in the static configurations directory.
.
Returns the file over TFTP and deletes it immediately (in the case of PNP, it notifies the device by providing a temporary URL on the web server).
The template is applied several times until substitution is complete, thus allowing deep file nesting.
Code |
|
Operation mode |
|
Redundancy mode |
|
Site types |
|
Layer |
|
Placement |
|
State preservation and recovery on restart |
|
Application |
|
Limitations
-
For TFTP to work, the option must be configured on the DHCP server.
-
PNP can serve only devices located in the network segment from which the server is reachable for broadcast messages.
-
Autoprovision specifics are individual for different phone brands and models; preparing the system for autoconfiguration may require preliminary testing and preparation of specific templates.
-
Some phone models store local configuration from settings made directly in the phone interface, which takes priority over settings distributed via autoprovision.
-
PNP security is ensured by the server’s broadcast address being unreachable from other network segments, while TFTP (default port 69) requires attention because MAC addresses can be brute-forced. When installing the server on a public address, consider disabling the autoprovision role from the configuration after the main system setup phase and after the configuration has been distributed to most subscriber devices.
-
Complex settings (using several SIP servers dependent on the domain, configuring several accounts on a phone, etc.) should be solved by designing specific templates.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
|
|
required |
Name. May consist of Latin letters and digits and must start with a letter. |
|
|
required |
Role type. Possible values: |
|
|
empty |
Additional role options. Contains a JSON object or list. |
|
|
empty |
Role activity flag. When set to false, the role does not participate in validation and is not started. |
|
|
empty |
Limit on the number of CPU logical cores used. Default: 0 - unlimited. |
|
|
empty |
Default logging level set specifically for the role instance (microservice type). More |
|
|
|
Flag allowing parameter differences in roles of the same group. Default: false - not allowed. |
|
|
69 |
TFTP service port |
|
|
|
Source port assignment policy for TFTP sessions.
|
|
|
empty |
Range of server UDP ports for initiating TFTP sessions with the first response. If the value is invalid, the 'random' policy is used. |
|
|
69 |
Specific server UDP port for initiating TFTP sessions with the first response to each client that made a request. |
|
|
|
Protocol for delivering configurations when using PNP. |
|
true |
Forced spam filter switch for the microservice instance. By default, the spam filter is not blocked but is inactive because master domain settings do not set the limit density. |
|
|
default |
TFTP request processing service mode. Values:
|
|
|
|
required |
Group number. When split into several groups, each active instance listens on the broadcast port for PNP requests. All instances receive the same PNP request simultaneously, but only the one that finds the requested MAC within its domains responds. |
|
|
required |
Order of the role instance within the group. |
|
|
empty |
List of domain names served by this group. |
|
|
Domain distribution group number. Instances with the same value share the domain subtree ( |
Substitution fields in templates
| Category | Description |
|---|---|
|
substitutes sipuser account field values. For example |
|
substitutes the domain name of the sipuser account. |
|
substitutes the SG proxy server address on the current site. More complex settings (specific port, multiple or distributed addressing) must be provided by creating specific templates in the project before mass device connection. |
|
substitutes a new UUID, making the configuration file unique each time. |
|
substitutes constant values. Constants are taken in descending priority: 1) from the account domain settings (settings.ap_constants), 2) from the master domain settings (settings.ap_constants), 3) from the site settings file (:SYNC/common/autoprovision/constants/SITE.cfg, /rest/v1/fs/targets/ap_constants/SITE.cfg, where SITE is the name of the site serving the request). |
|
performs an nslookup of the specified domain name and substitutes one of the discovered addresses. When the command is used repeatedly in a template, it guarantees substitution of different values. Can be used to substitute NTP server addresses when phones do not have access to the DNS service. |
|
substitutes another template file entirely. FILENAME must be the name of a file in the :SYNC/common/autoprovision/templates directory (/rest/v1/fs/targets/ap_templates). |
|
substitutes a random integer from 0 to N-1. Can be used for round-robin selection and substitution of a nested template (for example |
Configuration example
Configuration management is performed in an application available to master domain administrators. The application hides the full configuration content, but it is still available through the API.
The configuration contains a section describing all instances of all roles. Parameters are defined for each specific role instance.
{
"name": "ap1",
"roletype": "ap",
"group": 11360,
"order": 1,
"tftp_port": 69,
"pnp_url_proto": "tftp"
}