Telair Provisioning Bridge

Telair Provisioning Bridge

Telair customers’ Polycom phones still fetch their configuration from the legacy Telair provisioning server. SIPSTACK cannot reach that host, and the phones will not move on their own — each one keeps polling the address it was given until something on the legacy server tells it otherwise.

The bridge is that something: a one-off mv-ss-<tenant-slug>.cfg that you stage by hand on the legacy server and prepend to each device’s master CONFIG_FILES list. It sets the phone’s device.prov.* values to the SIPSTACK provisioning edge, so on its next provisioning cycle the phone re-points itself at Nova and stops coming back.

You use it once per tenant, during a Telair → Nova cutover. It is not part of normal device provisioning — phones already on Nova are covered by Devices.

Before you start

• You need the Manage PBX settings and devices permission (nova.settings.manage) — the same permission that gates Provisioning Access.
• You need write access to the legacy Telair provisioning server, and to each device’s master CONFIG_FILES list on it.
• The tenant comes from your Switchboard session. The request has no body and no tenant parameter, so you can only generate a bridge for the organization you are signed in to. To bridge a different tenant, sign in to that tenant.

Generating the bridge file

POST /v2/portal/nova/tenant/provisioning/mv-ss-bridge

No request body. The response returns:

Field	What it is
filename	mv-ss-<tenant-slug>.cfg — the exact name to stage the file under.
content	The rendered config file. This is the only copy — it is never stored, and the endpoint cannot hand it back later.
expiresAt	The instant the credential inside it is rotated automatically.
ttlHours	48.
configFilesHint	The precise CONFIG_FILES edit that makes the file take effect.
warning	The exposure summary, restated for whoever runs the cutover.

Generating a bridge rotates the tenant provisioning PIN. That is deliberate: a bridge can only carry a usable PIN if one was just minted (the stored PIN is a hash, never plaintext), and minting it here gives the exposure a known start instant. The previous PIN stays valid for the standard 24-hour grace window, so anything else already using it — a DHCP option 160 entry that hardcodes the PIN, for instance — must be updated inside that window. See Provisioning Access.

Save the file the moment you receive it. There is no way to retrieve it again; the only recovery is to generate another bridge, which rotates the PIN a second time.

Staging it — the order is load-bearing

1. Stage the file on the legacy Telair provisioning server, under the exact filename returned.

2. Prepend it to each device’s master CONFIG_FILES list:

   CONFIG_FILES="mv-ss-acme.cfg, <existing entries…>"

3. Wait for the phones to re-register against SIPSTACK Nova. The Polycom templates poll daily at 03:00, so a phone you do not reboot moves on its next poll.

4. Delete the file from the legacy server.

Step 4 is hygiene, not containment — see The exposure window for what actually retires the credential.

The bridge must be the FIRST entry

Polycom UCS resolves each parameter from the first file in CONFIG_FILES that declares it. A bridge listed after the legacy Telair configs is overridden by them: the phone keeps its old provisioning server, reports no error, and stays exactly where it was. Nothing tells you it failed — you find out because the phone never arrives.

If a mv-ss-*.cfg is already somewhere in the list, move that entry to the front rather than adding a second copy.

The exposure window

The bridge file contains device.prov.password — the tenant provisioning PIN, the single credential every phone in the tenant authenticates with. It is staged on the legacy Telair provisioning server, which serves plain HTTP with no authentication. For as long as the file is staged, the PIN is readable by anyone who can reach that host.

Deleting the file does not un-leak the PIN

Anyone who read the file while it was up still holds a working credential. Deletion removes the copy, not the knowledge. What retires the credential is rotation.

Point in time	What happens
Staged	The PIN is rotated. The exposure window opens here.
+ 48 hours (TTL)	The nova:mv-ss-bridge-expiry-sweep job rotates the PIN again. The PIN printed in the staged file is no longer the current one.
+ a further 24 hours (grace)	The superseded PIN still authenticates, so phones caught mid-migration are not stranded.
72 hours total	Worst case: the PIN in the staged file no longer works anywhere.

The sweep runs hourly, so the rotation lands within an hour of the 48-hour mark rather than exactly on it.

What that means in practice:

• Delete the staged file as soon as the phones have moved. Do not wait for the TTL. Every extra hour it is up is another hour the tenant’s PIN is readable by anyone who can reach the legacy host.
• Do not mirror or copy the file. Rotation kills the credential in every copy at once — but only when the TTL passes. A copy you forgot about stays readable for the whole window.
• Do not generate a bridge before you are ready to stage it. The clock starts when the file is generated, not when you edit CONFIG_FILES.

Limits

The TTL is fixed at 48 hours and is not settable per request. That is the point: no caller can widen the window in which a tenant-wide credential sits on an unauthenticated host. Changing it is a code change with a reviewer, not a request parameter.

The endpoint is rate limited — roughly 5 requests per minute per organization. Normal use never comes close, since a tenant needs one bridge. The limit also caps how quickly repeated calls can churn the tenant PIN, because every call rotates it.

Troubleshooting

The phone never moved. Almost always CONFIG_FILES ordering: the bridge is not the first entry, so the legacy configs win. Polycom raises no error for this. Re-check the list and put the bridge at the front.

The phone moved, then started getting 401 from the provisioning server. The PIN the bridge printed has been rotated and its grace window has closed. Check the current PIN in Provisioning Access and make sure the phone’s provisioning URL — DHCP option 160, or the value typed into the phone — carries it.

I lost the file. It is not retrievable. Generate another bridge; that rotates the PIN again and opens a fresh 48-hour window, so only do it when you are ready to stage the new file.