SIP-trunks

Een SIP-trunk verbindt je telefoonsysteem met Bird. De trunk geeft je PBX, het bedrijfstelefoonsysteem dat gesprekken routeert, een adres voor uitgaande gesprekken, bepaalt hoe Bird ze authenticeert en kan ook de gesprekken ontvangen die binnenkomen op de nummers die je hebt. Configureer trunks onder Voice > SIP Trunks.

Een SIP-trunk instellen doorloopt een volledige configuratie op volgorde, van het aanmaken van de trunk tot een testgesprek in elke richting.

De meeste opstellingen hebben één trunk nodig. Maak aparte trunks als locaties of systemen verschillende IP-allowlists, API-keys, sessiereferentie-instellingen of Digest-algoritmen nodig hebben.

Een trunk aanmaken

Selecteer Create trunk en voer een naam in. Je kunt dit dashboardlabel later wijzigen; het wordt niet met gesprekken meegestuurd.

Bird wijst een vast SIP-domein toe aan de trunk. Voer dit domein in je telefoonsysteem in zodat Bird gesprekken aan de trunk kan koppelen.

Een nieuwe trunk weigert elk gesprek totdat je aangeeft wie ze mag plaatsen: een IP-bereik, een API-key, sessiereferenties of een combinatie.

Gespreksrichting

Een trunk draagt elke richting afzonderlijk, en een nieuwe trunk draagt geen van beide. De trunkpagina heeft een sectie per richting, en een richting die uit staat toont alleen de schakelaar om hem in te schakelen.

Uitgaand bellen is je PBX die gesprekken plaatst via Bird. Selecteer Enable outbound. Zolang dit niet is ingeschakeld, weigert de trunk elke uitgaande poging ongeacht de referenties. De verbindingsgegevens, allowlists, keys, sessiereferenties en Digest-aanbieding van de trunk staan allemaal in deze sectie, omdat ze bepalen wat er mag verbinden.

Inkomend bellen is Bird die gesprekken aflevert bij je PBX, voor de nummers die deze trunk beantwoordt. Selecteer Enable inbound en stel daarna de Inbound routing van de trunk in: voeg ten minste één gateway toe, plaats die in een groep en laat de Default route naar die groep wijzen. Een trunk zonder gateway weigert elk inkomend gesprek naar zijn nummers, en dat geldt ook voor een opgeslagen standaardroute die op weigeren staat. De lijst Inbound numbers in de sectie toont welke van je nummers hun gesprekken hierheen sturen.

Een aflevergateway is het adres van je telefoonsysteem. Als je de laatste gateway verwijdert, blijft de inkomende instelling van de trunk ingeschakeld maar hebben inkomende gesprekken geen afleverdoel. Voeg een werkende gateway toe voordat je verkeer naar de trunk routeert. Je gateway moet het afgeleverde gesprek accepteren zonder Bird te vragen een SIP Digest-challenge te beantwoorden. Gesprekken afleveren bij een SIP-trunk legt groepen, regels en de standaardroute uit.

Laat een nummer naar de trunk wijzen vanaf de nummerpagina. Zie Gesprekken ontvangen voor instructies en een uitleg van de nummerformaten van gateways.

Waarschuwing: als je inkomend bellen uitschakelt, gaan alle nummers die naar deze trunk verwijzen terug naar de standaardroute van de werkruimte, en wordt een standaardroute die deze trunk noemt gereset naar weigeren. Weer inschakelen herstelt geen van beide. Het verwijderen van de trunk doet hetzelfde.

Verbindingsgegevens

Open een trunk om te zien wat je in je PBX moet invoeren:

Opmerking: met alleen de IP-allowlist heb je niet meer nodig dan het SIP-domein en een poort: de gebruikersnaam en het wachtwoord zijn voor API-key-authenticatie. Een client met een sessiereferentie gebruikt in plaats daarvan het wachtwoord uit die referentie.

Stuur je gesprekken naar het SIP-domein op een van deze poorten:

Audio encryption regelt de SRTP-versleuteling tussen je apparatuur en Bird, met SDES-sleutels die via TLS worden verstuurd. Nieuwe trunks gebruiken Preferred. Gesprekken die je apparatuur plaatst, worden versleuteld als die SDES via TLS aanbiedt. Gesprekken die worden afgeleverd bij een TLS-gateway (sips: of ;transport=tls) gebruiken versleuteling als die beschikbaar is, ook via een exitregio. Gesprekken op een trunk met media_bypass gebruiken onversleutelde audio. Een TLS-gateway die geen SRTP ondersteunt, beantwoordt versleutelde aanbiedingen met 488. Stel voor die gateway Off in of gebruik een sip:-URI. Required weigert onversleutelde gesprekken en vereist TLS voor elke gateway. Providers kunnen gesprekken onversleuteld verder doorgeven.

Bepalen wie gesprekken mag sturen

Een trunk kan apparatuur authenticeren op bron-IP-adres, API-key of een kortlevende sessiereferentie. Schakel de methoden in die je clients nodig hebben.

Configureer ze in IP allow list, Allowed API keys en Session credentials. Opgeslagen wijzigingen gelden voor nieuwe gesprekken.

IP-allowlist

Voeg de publieke adressen toe waarvandaan je apparatuur SIP verstuurt, als losse adressen of CIDR-bereiken, elk met een optionele beschrijving. Zodra de lijst een vermelding heeft, moeten gesprekken via IP-toelating of toegestane API-keys van een vermeld bereik komen. Ingeschakelde sessiereferenties bieden een apart toelatingspad en kunnen vanaf andere adressen worden gebruikt.

Voeg het publieke bronadres toe dat Bird bereikt. Gebruik voor apparatuur achter NAT het publieke adres van de router in plaats van het privéadres van het telefoonsysteem. Voor IP-toelating en toegestane API-keys weigert Bird gesprekken van niet-vermelde adressen op de SIP-laag, dus ze bereiken meestal niet het gesprekslogboek. Zie voice-probleemoplossing voor ontbrekende gesprekken.

API-key-authenticatie

Bird kan in plaats daarvan (of ook) elk gesprek om een wachtwoord vragen. De uitwisseling is SIP Digest-authenticatie: Bird stuurt een challenge, je telefoonsysteem antwoordt met een hash van het wachtwoord in plaats van het wachtwoord zelf, en Bird verifieert het tegen een Bird API-key.

1. Geef een API-key de voice-permissie op write-niveau; dat is het niveau waartegen een trunk authenticeert. Voeg het toe aan een key die je al hebt, of maak een nieuwe aan. In beide gevallen werkt het secret van de key ongewijzigd: een key die je al hebt uitgerold behoudt het secret waarmee je systemen zijn geconfigureerd, en een nieuwe key toont zijn secret eenmalig bij aanmaak, dus sla het dan op. Zie API-keys.
2. Voeg op de trunkpagina, onder Allowed API keys, die key toe.
3. Stel in je PBX de gebruikersnaam in op bird en het wachtwoord op het secret van de key.

Zodra de lijst een key heeft, vereist API-key-authenticatie een van de vermelde keys. Sessiereferenties blijven een aparte methode wanneer ze zijn ingeschakeld.

Als je de voice-permissie van een key verwijdert, stopt de authenticatie onmiddellijk, maar de trunk houdt de key in de toegestane lijst. Voeg de permissie weer toe en de trunk werkt opnieuw met hetzelfde secret, zonder dat je iets hoeft te wijzigen op de trunk of in je PBX. Zolang de permissie ontbreekt, markeert de trunkpagina de key als niet beschikbaar.

Het intrekken of verwijderen van een API-key verwijdert onmiddellijk de mogelijkheid om te authenticeren, op elke trunk die de key toestond, en dat is permanent. Roteer door eerst de nieuwe key aan de trunk toe te voegen, je apparatuur over te zetten en dan de oude in te trekken.

Sessiereferenties

Een sessiereferentie is een kortlevende SIP-gebruikersnaam en -wachtwoord. Ze beantwoordt dezelfde Digest-challenge als een API-key zonder een langlevend secret bloot te stellen.

Schakel ze in onder Session credentials op de trunkpagina; ze staan uit op een nieuwe trunk. Wat ze toelaten:

• De telefoon in het dashboard, die er per gesprek een voor je aanmaakt.
• Een SIP-client aangestuurd door de CLI: bird voice tools test-call maakt er een aan voor het gesprek dat het plaatst, en bird voice session-credentials create maakt er een aan om in een andere client te plakken. Beide hebben voice-toegang op write-niveau nodig.

Een referentie hoort bij de werkruimte in plaats van bij één trunk, dus een client kan deze op alle in aanmerking komende trunks gebruiken. De client moet de referentie aanbieden en de trunk moet sessiereferenties ingeschakeld hebben. Bird geeft het wachtwoord alleen terug bij het aanmaken.

Beschouw de geretourneerde vervaltijd als het laatste moment waarop de referentie een nieuw gesprek kan toelaten. Het subject dat de referentie heeft aangemaakt moet actief blijven: menselijke gebruikers hebben een werkruimterol of organisatie-eigenaar-toegang nodig; API-keys moeten tenant-overeenkomend, niet-ingetrokken en niet-verlopen blijven; serviceaccounts moeten actief blijven in dezelfde tenant. Belpermissie wordt gecontroleerd bij het aanmaken van de referentie. Latere subjectcontroles herberekenen die toekenning niet en beëindigen een al toegelaten gesprek niet.

Inschakelen verandert niets aan de manier waarop apparatuur op de IP-allowlist verbindt: een gesprek van een vermeld adres, op een trunk zonder toegestane API-keys, wordt nog steeds toegelaten zonder wachtwoordchallenge.

Digest-algoritme

Standaard biedt Bird eerst SHA-256 aan en daarna MD5. Je PBX antwoordt met het eerste algoritme dat het ondersteunt.

Wijzig de aanbieding onder Digest algorithm als je apparatuur dat vereist. Selecteer MD5 only voor een PBX die een challenge die begint met SHA-256 verkeerd afhandelt. Een trunk accepteert alleen de algoritmen die hij aanbiedt. API-keys werken met beide algoritmen en hoeven niet opnieuw te worden uitgegeven.

Houd MD5 in de aanbieding op elke trunk waarvandaan je belt via de telefoon: een browser antwoordt met MD5 en niets anders, dus een trunk die alleen SHA-256 aanbiedt weigert elk browsergesprek.

Een trunk verwijderen

Het verwijderen van een trunk gaat direct in: het SIP-domein accepteert geen nieuwe gesprekken meer en elk nummer dat ernaar wijst gaat terug naar de standaardroute van de werkruimte. Gesprekken die al bezig zijn gaan door, en de gespreksrecords via de trunk blijven in je Gesprekslogboek.

Vervolgstappen