Polycom autoprovisioning end-to-end — bootstrap.cfg, MAC-specific files, TLS provisioning

Polycom phones (VVX series and the newer Poly Edge) can pull their full configuration from a provisioning server on boot — no per-phone manual entry. This article walks the file hierarchy, the two ways to get phones to find the server, and the TLS setup that keeps your SIP credentials off the wire in plaintext.

The file hierarchy

A Polycom phone, on boot, looks for three layers of config:

1. 000000000000.cfg — the master config. Tells the phone the broad-strokes settings and lists which other files to load.
2. <MAC>.cfg — per-phone overrides. The MAC is the phone's hardware MAC in lowercase, no separators (e.g., 0004f2abcdef.cfg).
3. Any *.cfg referenced in the above — feature configs, dial plans, sip credentials, etc.

Polycom evaluates these in the order listed. MAC-specific overrides win over master config.

The bootstrap pattern that works

The convention is:

• 000000000000.cfg contains everything global — server addresses, dial plans, feature codes, ringtones — that every phone shares.
• <MAC>.cfg contains only what's unique to this phone: SIP credentials (extension number and password), the user's display name, line appearances.

This means you can pre-build a directory of per-MAC files for each phone you've shipped, and the phones provision themselves on first boot without touching the UI.

Minimal example

000000000000.cfg:

<?xml version="1.0" standalone="yes"?>
<polycomConfig>
    <reg
        reg.1.server.1.address="pbx.example.com"
        reg.1.server.1.port="5060"
        reg.1.server.1.transport="UDP"
        voIpProt.SIP.outboundProxy.address="pbx.example.com"
    />
    <dialplan
        dialplan.digitmap="[2-9]11|0T|+011xxx.T|[2-9]xxxxxxxxx"
    />
</polycomConfig>

0004f2abcdef.cfg (per-phone):

<?xml version="1.0" standalone="yes"?>
<polycomConfig>
    <reg
        reg.1.address="1001"
        reg.1.auth.userId="1001"
        reg.1.auth.password="strong-secret-here"
        reg.1.label="Front Desk"
        reg.1.displayName="Front Desk"
    />
</polycomConfig>

You serve these from a web server (HTTP or HTTPS); the phone fetches them on boot.

How phones find the provisioning server

Two methods, pick one:

DHCP option 66

The DHCP server hands out the provisioning URL alongside the IP lease:

# dnsmasq example
dhcp-option=66,"https://provision.example.com/polycom/"

# isc-dhcp-server
option tftp-server-name "https://provision.example.com/polycom/";

The phone reads option 66 on boot and starts there. Cleanest for office deployments where you control DHCP.

Manual / staged provisioning

Set the provisioning URL once via the phone UI or web interface (System → Provisioning Server). Useful for remote deployments where the customer's DHCP isn't yours, or for staged provisioning at your bench before shipping.

You can also use Polycom's ZTP (Zero Touch Provisioning) service to push a single bootstrap URL on first power-up. Worth the small setup cost if you're shipping many phones.

TLS provisioning

SIP credentials in the .cfg files are sensitive. Two mitigations:

• Serve over HTTPS. Phones fetch config over TLS; credentials don't traverse the network in cleartext. Polycom phones trust common CAs out of the box (Let's Encrypt is fine).
• Encrypt the config file itself. Polycom supports configuration file encryption with a per-MAC key. Generate the key on the provisioning server, ship the key to the phone via TLS bootstrap, then serve all subsequent configs encrypted. Detailed in Polycom's UC Software Provisioning Guide.

For most deployments, HTTPS-only provisioning is sufficient. Config file encryption is overkill unless you have specific compliance requirements.

Web server setup

nginx serving the config dir:

server {
    listen 443 ssl;
    server_name provision.example.com;

    ssl_certificate /etc/letsencrypt/live/provision.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/provision.example.com/privkey.pem;

    location /polycom/ {
        alias /var/www/polycom/;
        autoindex off;
        # Restrict by source IP if your phones come from known networks
        # allow 198.51.100.0/24;
        # deny all;
    }
}

Lock down with source-IP restriction if your phones are at known sites. For mobile / remote phones, leave it open but use strong per-extension SIP passwords and HTTPS.

Verifying provisioning

Boot the phone with the wrong-but-syntactically-valid SIP password set in your MAC.cfg, watch the logs (System → Diagnostic Logs). You should see:

• DHCP option 66 received (if using DHCP).
• HTTPS GET of 000000000000.cfg succeed.
• HTTPS GET of MAC.cfg succeed.
• SIP REGISTER attempt with the password from MAC.cfg.
• 403 response from PBX (because the password's wrong) — which confirms provisioning is working.

Then fix the password in MAC.cfg and let the phone re- provision.

Updating a deployed phone

Polycom phones poll the provisioning server periodically (default every 24 hours, configurable). Push a config change by updating the MAC.cfg on the server — the phone picks it up at the next poll, or sooner if you reboot it.

For an urgent change to a specific phone, force a re-check via the web interface (Settings → Provisioning Server → Update).