48ad2d416c235d6be31e7d5c7bbcbbdce6ce16d6
howto/telephony42-Asterisk.md
| ... | ... | @@ -0,0 +1,240 @@ |
| 1 | +# Getting Started with telephony42 (Asterisk) |
|
| 2 | + |
|
| 3 | +This guide will help you quickly deploy a working Asterisk PBX. By the end of this tutorial, you will be able to make and receive calls in telephony42. |
|
| 4 | + |
|
| 5 | +## Prerequisites |
|
| 6 | + |
|
| 7 | +Before configuring Asterisk, ensure you have: |
|
| 8 | + |
|
| 9 | +1. An allocated telephony42 (`+042`) number prefix registered in the registry (e.g., `+04240000`). |
|
| 10 | +2. DNS NAPTR records correctly configured on your zone in `tel.dn42`. |
|
| 11 | + |
|
| 12 | +Example of wildcard NAPTR record to route any calls to your PBX at `pbx.yourdomain.dn42` with SIP port `5060`: |
|
| 13 | + |
|
| 14 | +```bind |
|
| 15 | +*.0.0.0.0.4.2.4.0.tel.dn42. IN NAPTR 100 10 "u" "E2U+sip" "!^(.*)$!sip:\\1@pbx.yourdomain.dn42:5060!" . |
|
| 16 | +``` |
|
| 17 | + |
|
| 18 | +## Installation notes |
|
| 19 | + |
|
| 20 | +### Debian / Ubuntu |
|
| 21 | + |
|
| 22 | +Asterisk is available in the official repositories. (For Debian, you need to install packages from `sid` repository) |
|
| 23 | + |
|
| 24 | +```sh |
|
| 25 | +apt update |
|
| 26 | +apt install asterisk |
|
| 27 | +``` |
|
| 28 | + |
|
| 29 | +### Alpine |
|
| 30 | + |
|
| 31 | +```sh |
|
| 32 | +apk add asterisk |
|
| 33 | +``` |
|
| 34 | + |
|
| 35 | +### Docker (`docker compose`) |
|
| 36 | + |
|
| 37 | +```yaml |
|
| 38 | +services: |
|
| 39 | + asterisk: |
|
| 40 | + image: andrius/asterisk:stable |
|
| 41 | + container_name: asterisk42 |
|
| 42 | + network_mode: host |
|
| 43 | + volumes: |
|
| 44 | + - ./config:/etc/asterisk |
|
| 45 | + restart: unless-stopped |
|
| 46 | +``` |
|
| 47 | + |
|
| 48 | +# Example configuration |
|
| 49 | + |
|
| 50 | +Asterisk relies on many configuration files. This guide will focus only on two main config files: |
|
| 51 | +- `pjsip.conf`: Network, Endpoints, and Authentication |
|
| 52 | +- `extensions.conf`: Dialplan and Routing |
|
| 53 | + |
|
| 54 | +When copying the configurations below, replace the following variables (remove the brackets): |
|
| 55 | +* `<OWN_IPv4>`: Your dn42 IPv4 address (e.g., `172.20.X.X`) |
|
| 56 | +* `<OWN_IPv6>`: Your dn42 IPv6 address (e.g., `fdXX::X`) |
|
| 57 | +* `<OWN_PREFIX>`: Your telephony prefix (e.g., `+04240000`) |
|
| 58 | +* `<EXT_NAME>`: Name for your extension (e.g., `0001` or `my-phone`) |
|
| 59 | +* `<FULL_NUMBER>`: The full `+042` number for your extension (e.g., `+042400000001`) |
|
| 60 | +* `<SECRET_PASS>`: A strong password |
|
| 61 | + |
|
| 62 | +## PJSIP (`pjsip.conf`) |
|
| 63 | + |
|
| 64 | +This file defines how Asterisk listens to the network, sets up templates for devices, creates your local extension, and prepares an anonymous endpoint to catch incoming ENUM calls. |
|
| 65 | + |
|
| 66 | +```ini |
|
| 67 | +[global] |
|
| 68 | +type=global |
|
| 69 | +# verified peers first |
|
| 70 | +endpoint_identifier_order=auth_username,username,ip |
|
| 71 | + |
|
| 72 | +; ========================================== |
|
| 73 | +; Transports |
|
| 74 | +; ========================================== |
|
| 75 | + |
|
| 76 | +[transport-udp4] |
|
| 77 | +type=transport |
|
| 78 | +protocol=udp |
|
| 79 | +bind=<OWN_IPv4>:5060 |
|
| 80 | +local_net=172.20.0.0/14 |
|
| 81 | +local_net=172.31.0.0/16 |
|
| 82 | +local_net=10.0.0.0/8 |
|
| 83 | + |
|
| 84 | +[transport-udp6] |
|
| 85 | +type=transport |
|
| 86 | +protocol=udp |
|
| 87 | +bind=[<OWN_IPv6>]:5060 |
|
| 88 | +local_net=fd00::/8 |
|
| 89 | + |
|
| 90 | +; ========================================== |
|
| 91 | +; Templates |
|
| 92 | +; ========================================== |
|
| 93 | + |
|
| 94 | +[phone-template](!) |
|
| 95 | +type=endpoint |
|
| 96 | +context=context-local ; Incoming calls from this phone go here |
|
| 97 | +allow=!all,opus,g722,alaw,ulaw ; Prioritize Opus and G.722 HD audio |
|
| 98 | +rtp_symmetric=yes |
|
| 99 | +force_rport=yes |
|
| 100 | +rewrite_contact=yes |
|
| 101 | +direct_media=no ; Proxy media through PBX to prevent NAT issues |
|
| 102 | +trust_id_inbound=yes |
|
| 103 | +send_pai=yes |
|
| 104 | + |
|
| 105 | +; ========================================== |
|
| 106 | +; Local Extensions |
|
| 107 | +; ========================================== |
|
| 108 | + |
|
| 109 | +; Replace variables to create an extension names <EXT_NAME> |
|
| 110 | +[<EXT_NAME>](phone-template) |
|
| 111 | +auth=<EXT_NAME> |
|
| 112 | +aors=<EXT_NAME> |
|
| 113 | +callerid="My Name" <<FULL_NUMBER>> |
|
| 114 | + |
|
| 115 | +[<EXT_NAME>] |
|
| 116 | +type=auth |
|
| 117 | +auth_type=userpass |
|
| 118 | +username=<EXT_NAME> |
|
| 119 | +password=<SECRET_PASS> |
|
| 120 | + |
|
| 121 | +[<EXT_NAME>] |
|
| 122 | +type=aor |
|
| 123 | +max_contacts=3 ; Allow 3 devices to register simultaneously |
|
| 124 | +remove_existing=yes |
|
| 125 | + |
|
| 126 | +; ========================================== |
|
| 127 | +; Incoming calls via ENUM |
|
| 128 | +; ========================================== |
|
| 129 | + |
|
| 130 | +[peer-enum-inbound] |
|
| 131 | +type=endpoint |
|
| 132 | +context=context-enum ; Send unknown incoming calls to ENUM context |
|
| 133 | +allow=!all,opus,g722,alaw,ulaw |
|
| 134 | +rtp_symmetric=yes |
|
| 135 | +force_rport=yes |
|
| 136 | +rewrite_contact=yes |
|
| 137 | +direct_media=no |
|
| 138 | + |
|
| 139 | +[peer-enum-inbound-id] |
|
| 140 | +type=identify |
|
| 141 | +endpoint=peer-enum-inbound |
|
| 142 | +; match all dn42 subnets |
|
| 143 | +match=172.20.0.0/14 |
|
| 144 | +match=172.31.0.0/16 |
|
| 145 | +match=10.0.0.0/8 |
|
| 146 | +match=fd00::/8 |
|
| 147 | + |
|
| 148 | +; ========================================== |
|
| 149 | +; Outgoing calls via ENUM |
|
| 150 | +; ========================================== |
|
| 151 | + |
|
| 152 | +[peer-enum-outbound] |
|
| 153 | +type=endpoint |
|
| 154 | +allow=!all,opus,g722,alaw,ulaw |
|
| 155 | +send_pai=yes |
|
| 156 | +``` |
|
| 157 | + |
|
| 158 | +## Dialplan (`extensions.conf`) |
|
| 159 | + |
|
| 160 | +The file tells Asterisk how to route numbers. It is divided into serveral contexts. |
|
| 161 | + |
|
| 162 | +```ini |
|
| 163 | +[globals] |
|
| 164 | +; (Optional) Global variables can go here |
|
| 165 | + |
|
| 166 | +; ========================================== |
|
| 167 | +; Inbound Routing |
|
| 168 | +; ========================================== |
|
| 169 | + |
|
| 170 | +; Calls originating from your own network. |
|
| 171 | +[context-local] |
|
| 172 | + |
|
| 173 | +; 4 digits -> call local extension |
|
| 174 | +exten => _XXXX,1,Goto(ext-local,${EXTEN},1) |
|
| 175 | + |
|
| 176 | +; starts with 042 -> add + and route out |
|
| 177 | +exten => _042X.,1,Goto(ext-routing,+${EXTEN},1) |
|
| 178 | + |
|
| 179 | +; standard +042 dialing -> route out |
|
| 180 | +exten => _+042X.,1,Goto(ext-routing,${EXTEN},1) |
|
| 181 | + |
|
| 182 | +; Catch-all -> add +042 and route out |
|
| 183 | +exten => _X!,1,Goto(ext-routing,+042${EXTEN},1) |
|
| 184 | + |
|
| 185 | + |
|
| 186 | +Calls originating from external networks via ENUM. |
|
| 187 | +[context-enum] |
|
| 188 | + |
|
| 189 | +; starts with 00 -> replace with + and route out |
|
| 190 | +exten => _00X!,1,Goto(ext-routing,+${EXTEN:2},1) |
|
| 191 | + |
|
| 192 | +; starts with + -> route out |
|
| 193 | +exten => _+X!,1,Goto(ext-routing,${EXTEN},1) |
|
| 194 | + |
|
| 195 | +; Catch-all -> add + and route out |
|
| 196 | +exten => _X!,1,Goto(ext-routing,+${EXTEN},1) |
|
| 197 | + |
|
| 198 | + |
|
| 199 | +; ========================================== |
|
| 200 | +; Outbound & Local Routing |
|
| 201 | +; ========================================== |
|
| 202 | + |
|
| 203 | +; Calls destined for local networks. |
|
| 204 | +[ext-local] |
|
| 205 | +; route <OWN_PREFIX>0001 calls to your local extension <EXT_NAME> |
|
| 206 | +exten => 0001,1,Dial(PJSIP/<EXT_NAME>,30) ; |
|
| 207 | + |
|
| 208 | + |
|
| 209 | +; Inter-PBX routing for both inbound and outbound calls. |
|
| 210 | +[ext-routing] |
|
| 211 | + |
|
| 212 | +; route calls destined for your prefix |
|
| 213 | +exten => _<OWN_PREFIX>.,1,Goto(ext-local,${EXTEN:9},1) |
|
| 214 | + |
|
| 215 | +; other external calls -> do ENUM lookup on tel.dn42 |
|
| 216 | +exten => _+042X.,1,Set(TARGET_URI=${ENUMLOOKUP(${EXTEN},sip,,,tel.dn42)}) |
|
| 217 | + ; if found, dial via our outbound endpoint |
|
| 218 | + same => n,ExecIf($["${TARGET_URI}"!=""]?Dial(PJSIP/peer-enum-outbound/sip:${TARGET_URI},60)) |
|
| 219 | + ; if unallocated or failed, naturally hangup |
|
| 220 | + same => n,Hangup() |
|
| 221 | +``` |
|
| 222 | + |
|
| 223 | +Apply your configuration by entering the Asterisk CLI: |
|
| 224 | + |
|
| 225 | +```sh |
|
| 226 | +asterisk -rx 'core reload' |
|
| 227 | +``` |
|
| 228 | + |
|
| 229 | +# Setting up your extension |
|
| 230 | + |
|
| 231 | +You can now connect a softphone (like MicroSIP, Zoiper, or Linphone) or a hardware IP Phone/ATA using the following details: |
|
| 232 | + |
|
| 233 | +* Domain / Server: pbx.yourdomain.dn42 / `<OWN_IPv4>` or `<OWN_IPv6>` |
|
| 234 | +* Port: 5060 (UDP) |
|
| 235 | +* Username: `<EXT_NAME>` |
|
| 236 | +* Password: `<SECRET_PASS>` |
|
| 237 | + |
|
| 238 | +Once connected, ask a friend in telephony42 to call your `<FULL_NUMBER>`. |
|
| 239 | + |
|
| 240 | +*Tip: Install and use `sngrep -c` in your PBX's terminal to visually monitor SIP traffic if calls fail.* |