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.
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 voeg dan ten minste één aflevergateway toe: een trunk zonder gateway weigert elk inkomend gesprek naar zijn nummers. De lijst Inbound numbers in de sectie toont welke van je nummers hun gesprekken hierheen sturen.
Een nummer naar de trunk laten wijzen doe je op het nummer, niet hier. Zie Gesprekken ontvangen daarvoor, en voor wat de nummerformaten van een gateway doen.
Warning: turning inbound calling off puts every number pointing at this trunk back on reject, and turning it back on does not restore them. Deleting the trunk does the same.
Verbindingsgegevens
Open een trunk om te zien wat je in je PBX moet invoeren:
| Instelling | Waarde |
|---|---|
| SIP-domein | Het eigen domein van de trunk. Kopieer het volledig van de trunkpagina |
| Gebruikersnaam | Altijd bird |
| Wachtwoord | Het secret van een API-key die op deze trunk is toegestaan (zie API-key-authenticatie) |
Note: with the IP allow list alone, the SIP domain and a port are all you need: the username and password are for API key authentication. A client holding a session credential uses the password from that credential instead.
Stuur je gesprekken naar het SIP-domein op een van deze poorten:
| Transport | Poort | Opmerkingen |
|---|---|---|
| UDP | 5060 | De standaard die de meeste apparatuur aanneemt |
| TCP | 5060 | Dezelfde poort als UDP, dus kies het transport op je PBX |
| TLS | 5061 | SIP over TLS, voor signalering die je onderweg versleuteld wilt |
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. IP-filtering wordt actief zodra de lijst één vermelding heeft: vanaf dat moment mogen alleen vermelde bereiken gesprekken naar deze trunk sturen.
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. Bird weigert 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.
- 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.
- Voeg op de trunkpagina, onder Allowed API keys, die key toe.
- Stel in je PBX de gebruikersnaam in op bird en het wachtwoord op het secret van de key.
API-key-authenticatie wordt actief zodra de lijst één key heeft: vanaf dat moment mogen alleen de keys die je vermeldt authenticeren.
Het verwijderen van de voice-permissie van een key 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 iets te wijzigen op de trunk of in je PBX. Zolang de permissie ontbreekt, markeert de trunkpagina die key zodat de toegestane lijst nooit als werkend leest wanneer dat niet zo is.
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.
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 het weigeren van gesprekken. Gesprekken die al bezig zijn gaan door, en de gespreksrecords via de trunk blijven in je Gesprekslogboek.
Vervolgstappen
| Pagina | Wat het behandelt |
|---|---|
| Je eerste gesprek plaatsen | Van een lege werkruimte tot een rinkelende telefoon |
| Telefoon | Bellen vanuit het dashboard, via een trunk die sessiereferenties accepteert |
| Gesprekken plaatsen | Wat Bird verwacht op de INVITE, en wat een gesprek kost |
| Gesprekken ontvangen | Een nummer naar deze trunk laten wijzen en de afleveringsgateways ervan |
| Beller-ID's | Een nummer registreren en bewijzen dat het van jou is met een verificatiegesprek |
| API-keys | Een key aanmaken, de scopes kiezen en roteren |
Gerelateerde bronnen
Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.