Autoprovision processor (ap)

Table of Contents

Description
Limitations
Parameters
- Substitution fields in templates
Configuration example
See also

Description

Autoprovisioning Processor. Processes requests from devices received via TFTP and PNP.

Reserved. Active-Active is used for TFTP processes. Active-Passive for PNP processes and MAC address cache management.

When a TFTP request is received, the first thing it looks for is a ready file in the :SYNC/common/autoprovision/configurations directory (control is also available via the REST-API master domain /rest/v1/fs/targets/ap_configurations).
If the file is not detected, an attempt is made to locate the template, fill and return.
1. The MAC address is extracted from the file name.
2. The sipuser account is discovered by MAC (field `opts.ap_devices.mac or opts.ap_mac_address`). The search is performed in all domains.
3. By file name, the template name mask in `MasterDomain.settings.ap_options.masks` is detected. Perhaps the mask contains a type, then it acts as the final extension of the file when searching for the template.
4. The device model is determined by the account (field `opts.ap_devices.device_model bkb 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 (located in the :SYNC/common/autoprovision/templates directory and available via the 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`), site constants (`:SYNC/common/autoprovision/constants/<SiteName>.cfg`), Section [blf] - populated via multiple substitution of the template for the BLF taken for the detected device model and populated based on the list (field `opts.ap_devices.blf or ext.ap_blf`).
7. The template is supplemented or adjusted by individual settings (field `opts.ap_devices.override` or `ext.ap_override`). The result is returned to the device for autotuning.
.
If it is necessary to provide downloads of firmware and other files that do not depend on the MAC address, they should be placed in the static configuration directory.
.
Returns the file via TFTP and deletes it immediately (in case of PNP notifies the device by providing a temporary URL on the webserver).

The pattern is applied several times until the substitution is complete, thus allowing for deep file attachments.

Table 1. System Characteristics

Code	`ap`
Mode of operation	`Service`
Backup mode	`Active-Active (for TFTP), Active-Passive (for PNP and MAC address cache management).`
Types of sites	`Any`
Layer	`Business logic`
Placement	`Internal or border (access from telephone devices)`
Saving and restoring state on reboot	`No`
appendix	`era_ap`

Limitations

For TFTP to work, the option must be written to the DHCP server.
PNP can only serve devices on the network segment from which the server is accessible for broadcast messages.
The specifics of autoprovisioning are individualized for different makes and models of phones; preparing the system for autoprovisioning may require preliminary testing efforts and preparation of specific templates.
Some phone models store local configuration from settings set directly in the phone’s interface, which takes precedence over settings distributed through the autoprovision.
PNP security is ensured by the inaccessibility of the server’s broadcast address to other network segments, while TFTP (default port 69) requires attention as MAC address brute force is possible. When installing the server on a public address, consider disabling the autoprovisioning role from the configuration after the main system setup phase and distributing the configuration to most subscriber devices.
Complex customizations (using multiple domain dependent sip servers, setting up multiple accounts on the phone, etc.) should be handled by project specific templates.

Parameters

Description of columns in the table

Table 2. Parameters
Name	Type	Default	Description
`name`	`str`	required	Name. May consist of Latin letters and numbers, must begin with a letter.
`roletype`	`str`	required	Role Type. Possible values: `"ap"`.
`iface`	`str`	required	The alias of the server network interface on which the roles will interact internally with each other.
`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.
`tftp_port`	`int`	69	Port of Service TFTP
`pnp_url_proto`	`str`	`tftp`	Protocol for configuration handoffs when using PNP. Possible options: `tftp`, `http`. In the first case the file is given from TFTP server of autoprovision role, in the second case - from temporary file on webserver.
`group`	`int`	required	Group Number. As part of horizontal scaling, a role can be divided into multiple groups on a site, with only one instance active in each group and the rest reserved. Responsibilities between groups are shared across domain sets. Together, all groups maintain a complete domain set. All roles in the same group must have the same responsibility. Integer from `1` to `9999999`.
`order`	`int`	required	The order of a role instance within a group. Defines in what order the flow in the mode will take place Active-Passive.
`include_domains`	`array<str>`	empty	A list of domain names served by this group. Any domain of any level can be specified. Specifying a domain causes its subdomain tree to be served on this group and not on other role groups, excluding only those branches mentioned in other groups. Collectively, all role groups on a site serve a complete domain tree.

Substitution fields in templates

Table 3. Categories
Category	Description
`[sipuser.KEY]`	substitutes the values of the sipuser account fields. For example `[sipuser.login]` or `[sipuser.ext.my_obj.my_key]`.
`[constants.domain]`	substitutes the domain name of the account sipuser.
`[constants.sg.addr]`	substitutes the address of the SG proxy server at the current site. More complex settings (specific port, multiple or distributed addressing) should be provided by creating specific templates in the project before mass connection of devices.
`[constants.newid]`	substitutes a new UUID, making the configuration file unique every time.
`[constants.KEY]`	substitutes the values of constants. The constants are taken with decreasing 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 nslookup query of the specified domain name and substitutes one of the detected addresses. In case of multiple use of the command in the template, it guarantees substitution of different values. Can be used to substitute addresses of NTP servers in case phones do not have access to the service DNS).
`[include.FILENAME]`	substitutes the entire other template file. FILENAME must be replaced by the name of the file in the directory :SYNC/common/autoprovision/templates (/rest/v1/fs/targets/ap_templates).
`[random.N]`	substitutes a random integer value from 0 to N-1. Can be used for round-robin selection and substitution of a nested pattern (e.g. `[include.sg[random,5]]`).

Configuration example

The configuration is managed in an application available to master domain administrators. The application hides the full content of the configuration, but it is nevertheless accessible via the API.

The configuration contains a section to describe all instances of all roles. Parameters are defined for each specific role instance.

Example node

{
    "name": "ap1",
    "roletype": "ap",
    "iface": "eth0",

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

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