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.

Table 1. System characteristics

Code

ap

Operation mode

Service

Redundancy mode

Active-Active

Site types

Any

Layer

Business logic

Placement

Internal or border (accessible from phone devices)

State preservation and recovery on restart

No

Application

era_ap

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

Table 2. Parameters
Name Type Default Description

name

str

required

Name. May consist of Latin letters and digits and must start with a letter.

roletype

str

required

Role type. Possible values: "ap".

ext

json

empty

Additional role options. Contains a JSON object or list.

enabled

bool

empty

Role activity flag. When set to false, the role does not participate in validation and is not started.

limit_of_cores

int

empty

Limit on the number of CPU logical cores used. Default: 0 - unlimited.

logging_default_level

int

empty

Default logging level set specifically for the role instance (microservice type). More

allow_divergence

bool

false

Flag allowing parameter differences in roles of the same group. Default: false - not allowed.

tftp_port

int

69

TFTP service port

tftp_source_port_policy

str

random

Source port assignment policy for TFTP sessions.
Possible values:

  • random - a random port is selected for each session.

  • range - a random port from the specified range is selected for each session (tftp_source_port_range parameter).

  • port - the same outgoing port is used for all sessions (tftp_source_port parameter). This mode does not comply with RFC 1350 and is not recommended.

tftp_source_port_range

str

empty

Range of server UDP ports for initiating TFTP sessions with the first response.
Used in tftp_source_port_policy = range mode.
Value format: FromPort:Count, for example "50000:1000".

If the value is invalid, the 'random' policy is used.

tftp_source_port

int

69

Specific server UDP port for initiating TFTP sessions with the first response to each client that made a request.
Used in tftp_source_port_policy = port mode.
Possible values from 1 to 65535.

pnp_url_proto

str

tftp

Protocol for delivering configurations when using PNP.
Possible values: tftp, http. In the first case, the file is served from the autoprovision role’s TFTP server; in the second, from a temporary file on the web server.

anti_spam_enabled

bool

true

Forced spam filter switch for the microservice instance.
The limit density is configured by border filter rules and the master domain parameter mps_limit_defaults → sip.

By default, the spam filter is not blocked but is inactive because master domain settings do not set the limit density.

mode

str

default

TFTP request processing service mode. Values:

  • default - normal mode, where files are generated from templates on disk when MAC addresses match those assigned in sipuser account properties.

  • dm - new mode with request redirection to the device manager (since version 1.11). The product layer must be installed and redirection configured.

group

int

required

Group number.
As part of horizontal scaling, the role can be split into several groups on a site, in each of which only one instance is active and the rest are standby.
Responsibility is divided between groups by domain sets. Together all groups serve the full domain set. All roles in one group must have the same responsibility.

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.
TFTP ports must differ between groups. The default TFTP port can be served by only one group.
An integer from 1 to 9999999.

order

int

required

Order of the role instance within the group.
Determines the order in which takeover occurs in Active-Passive mode.

include_domains

array<str>

empty

List of domain names served by this group.
Any domain of any level can be specified. Specifying a domain causes its subtree to be served on this group and not on other role groups, except for branches mentioned in other groups.
Together, all role groups on the site serve the full domain tree.

domain_group

int

group

Domain distribution group number. Instances with the same value share the domain subtree (include_domains) as one group. Defaults to the group number.
An integer from 0.

Substitution fields in templates

Table 3. Categories
Category Description

[sipuser.KEY]

substitutes sipuser account field values. For example [sipuser.login] or [sipuser.ext.my_obj.my_key].

[constants.domain]

substitutes the domain name of the sipuser account.

[constants.sg.addr]

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.

[constants.newid]

substitutes a new UUID, making the configuration file unique each time.

[constants.KEY]

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).

[nslookup.DOMAINNAME]

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.

[include.FILENAME]

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).

[random.N]

substitutes a random integer from 0 to N-1. Can be used for round-robin selection and substitution of a nested template (for example [include.sg[random,5]]).

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.

Node example
{
    "name": "ap1",
    "roletype": "ap",

    "group": 11360,
    "order": 1,

    "tftp_port": 69,
    "pnp_url_proto": "tftp"
 }

See also