asterisk-configs/asterisk/README.md

# Installation from package repository

> Each version of Asterisk is unstable and may contain many bugs.
{.is-warning}

```
sudo apt update
sudo apt install asterisk
```

> The package in APT is usually outdated, but rather stable.
{.is-warning}

To restart the Asterisk service:
```
sudo systemctl restart asterisk
```

To close the Asterisk service:
```
sudo systemctl stop asterisk
```

## Testing

To test, let's connect to the Asterisk console:
```
sudo rasterisk
```

Which will bring you into the Asterisk command-line client. You will see this prompt after the basic Asterisk information is displayed:
```
asterisk*CLI>
```

To change the verbosity of the console, use the following:
```
core set verbose 4
```

To check the version of Asterisk, enter:
```
sudo rasterisk -V
```

If any error occurs, you can see the service log or logs from files:
```
sudo journalctl -eu asterisk -f
sudo vim /var/log/asterisk/full
```

# pjsip.conf
<kbd>res_pjsip</kbd> configuration is stored in <kbd>pjsip.conf</kbd>.

To activate PJSIP add chan_sip to noload and delete res_pjsip in <kbd>modules.conf</kbd>.

```
noload => chan_sip.so
;noload => res_pjsip.so
```

## Intercom
```
[domofon]
type=endpoint
direct_media=no
rtp_symmetric=yes
force_rport=yes
rewrite_contact=yes
allow=alaw,h264
transport=transport-udp
context=internal
aors=domofon
auth=domofon

[domofon]
type=auth
auth_type=userpass
password=your_password
username=domofon

[domofon]
type=aor
max_contacts=1
```

### Endpoint

| Variable        | Description |
| ----------- 		| ----------- |
| direct_media    | determines whether media may flow directly between endpoints (default: "yes")
| rtp_symmetric   | user agents (UAs) use the same socket/port binding to send and receive RTP stream packets
| force_rport   	| causes Asterisk to always send responses back to the address/port from which it received requests
| rewrite_contact | allow contact header to be rewritten with the source IP address port (default: "no")
| allow   				| allow codecs in order of preference
| transport		    | set the default transports; the order determines the primary default transport
| context				  | default context for incoming calls (from <kbd>extensions.conf</kbd>); defaults to 'default'
| aors				    | AoRs to be used with the endpoint (default: "")
| auth				    | authentication objects associated with the endpoint (default: "")

### Auth

| Variable        	| Description |
| ----------- 			| ----------- |
| auth_type    			| may be "userpass" for plain text passwords or "md5" for pre-hashed credentials. (default: "userpass")
| password, username| credentials for registration


### AoR

| Variable        	| Description |
| ----------- 			| ----------- |
| max_contacts    	| maximum number of contacts that can bind to an AoR (default: "0")

## Client
This configuration example is for registering a client application with Asterisk using WebRTC.

```
[15]
type=endpoint
direct_media=no
context=from-external
allow=vp8,vp9,h264,alaw
transport=transport-wss
webrtc=yes
auth=15
aors=15

[15]
type=auth
auth_type=userpass
password=your_password
username=15

[15]
type=aor
max_contacts=10
```

| Variable        	| Description |
| ----------- 			| ----------- |
| webrtc    				| when set to "yes" this also enables the following values that are needed for webrtc: rtcp_mux, use_avpf, ice_support, and use_received_transport

> VP8/VP9 are the default codecs for WebRTC and the only codec for intercom is H264.
> In this case, a codec difference problem may occur.
> At the time of writing only Freeswitch can transcode video from one codec to another.
{.is-warning}

> You can use any name for the client. 
> I chose <kbd>15</kbd> because it is convenient to call from a smartphone with a fake client (I use Zoiper).
{.is-info}

# extensions.conf
```
;-------------------------------------------------------
;       General Section
;-------------------------------------------------------
[general]
static=yes
writeprotect=yes
clearglobalvars=yes
autofallthrough=yes

[from-external]
exten => 200,1,Dial(PJSIP/domofon,120)

[invalid]
exten => _X,1,Stasis(hello)
same => n,Dial(PJSIP/${EXTEN}&PJSIP/comfortech/${EXTEN},120)
same => n,Hangup
exten => _XX,1,Stasis(hello)
same => n,Dial(PJSIP/${EXTEN}&PJSIP/comfortech/${EXTEN},120)
same => n,Hangup

exten => _1[0-3]X,1,Stasis(hello)
same => n,Dial(PJSIP/${EXTEN}&PJSIP/comfortech/${EXTEN},120)
same => n,Hangup

[default]
```

`static`
if static is set to no, or omitted, then the pbx_config will rewrite this file when extensions are modified. 

`writeprotect`
if static=yes and writeprotect=no, you can save dialplan by CLI command <kbd>dialplan save</kbd> too

`clearglobalvars`
if clearglobalvars is set, global variables will be cleared and reparsed on a <kbd>dialplan reload</kbd>, or Asterisk reload.

`autofallthrough`
if autofallthrough is set, then if an extension runs out of things to do, it will terminate the call with BUSY, CONGESTION
if autofallthrough is not set, then if an extension runs out ofthings to do, Asterisk will wait for a new extension to be dialed

`_X`, `_XX`, `_1[0-3]X`
it means that dialplans will work with 1-139 numbers

`${EXTEN}`
variable equal to dialed number

# WebRTC
WebRTC requires **WSS (WebSocket Secure)** and we need a domain with a certificate. You can use a self-signed certificate, but you cannot use it with a browser and sipML5.

## Generate certificate

**Let’s Encrypt** is a service offering free SSL certificates through an automated API. The most popular Let’s Encrypt client is EFF’s **Certbot**.

Install Certbot:
```
sudo add-apt-repository ppa:certbot/certbot
sudo apt-get update
sudo apt-get install certbot
```

Certbot needs to answer a cryptographic challenge issued by the Let’s Encrypt API in order to prove we control our domain. It uses ports 80 (HTTP) or 443 (HTTPS) to accomplish this. Open up the appropriate port in your firewall:

```
sudo ufw allow 80
```

Substitute 443 above if that’s the port you’re using. ufw will output confirmation that your rule was added:

> Output
> Rule added
> Rule added (v6)
{.is-success}

We can now run Certbot to get our certificate. We’ll use the <kbd>--standalone</kbd> option to tell Certbot to handle the challenge using its own built-in web server. The <kbd>--preferred-challenges</kbd> option instructs Certbot to use port 80 or port 443. If you’re using port 80, you want <kbd>--preferred-challenges</kbd> http. For port 443 it would be <kbd>--preferred-challenges</kbd> tls-sni. Finally, the <kbd>-d</kbd> flag is used to specify the domain you’re requesting a certificate for. You can add multiple <kbd>-d</kbd> options to cover multiple domains in one certificate.

```
sudo certbot certonly --standalone --preferred-challenges http -d example.com
```

## Configure Asterisk with cerificate

This certificate can only be accessed by the <kbd>root</kbd> user. Asterisk is executed by <kbd>asterisk</kbd> user. The way to fix this problem is to copy the certificate into Asterisk directory and change the owner.

If you use Asterisk as a Linux service:
```
mkdir /etc/asterisk/keys
sudo cp -L /etc/letsencrypt/live/example.com/cert.pem /etc/asterisk/keys
sudo cp -L /etc/letsencrypt/live/example.com/privkey.pem /etc/asterisk/keys
sudo chown asterisk:asterisk /etc/asterisk/keys/cert.pem
sudo chown asterisk:asterisk /etc/asterisk/keys/privkey.pem
```

You need to enable TLS and add the certificate to <kbd>http.conf</kbd>:
```
[general]
enabled=no
tlsenable=yes
tlsbindaddr=0.0.0.0:8089
tlscertfile=/etc/asterisk/keys/cert.pem
tlsprivatekey=/etc/asterisk/keys/privkey.pem
```

## Testing

You can use one of 2 sites to test WebRTC from your browser:
- https://www.doubango.org/sipml5/call.htm
- https://tryit.jssip.net/

# HTTP server (ARI)
The HTTP server in Asterisk is configured via http.conf. Note that this does not describe all of the options available via http.conf - rather, it lists the most useful ones for ARI.

Example:
```
[general]
enabled = yes
bindaddr = 0.0.0.0
bindport = 8088
```

| Variable    | Description |
| ----------- | ----------- |
| enabled     | Enable the HTTP server. The HTTP server in Asterisk is disabled by default. Unless it is enabled, ARI will not function!
| bindaddr    | The IP address to bind the HTTP server to. This can either be an explicit local address, or 0.0.0.0 to bind to all available interfaces.
| bindport    | The port to bind the HTTP server to. Client making HTTP requests should specify 8088 as the port to send the request to.
| prefix      | A prefix to require for all requests. If specified, requests must begin with the specified prefix.
| tlsenable   | Enable HTTPS
| tlsbindaddr | The IP address and port to bind the HTTPS server to. This should be an IP address and port, e.g., 0.0.0.0:8089
| tlscertfile | The full path to the certificate file to use. Asterisk only supports the .pem format
| tlsprivatekey| The full path to the private key file. Asterisk only supports the .pem format. If this is not specified, the certificate specified in tlscertfile will be searched for the private key.

For creating a certificate, see [WebRTC configuration](/telecom/Asterisk/webrtc)

# Fail2Ban

To install fail2ban:
```
sudo apt install fail2ban
```

The default settings of the program are in the <kbd>/etc/fail2ban/jail.conf</kbd> file, it is recommended to change the settings in <kbd>/etc/fail2ban/jail.local</kbd>, which is a copy of <kbd>jail.conf</kbd>.

The file contains a section of general settings <kbd>[DEFAULT]</kbd> and sections of specific settings for certain services (for example, the presence of the <kbd>[ssh]</kbd> section is demonstrated).

```
[DEFAULT]
ignoreip = 127.0.0.1/8
ignorecommand =
bantime  = 3600
findtime = 600
maxretry = 3
backend = auto
usedns = warn
destemail = root@localhost
sendername = Fail2Ban
sender = fail2ban@localhost
banaction = iptables-multiport
mta = sendmail
protocol = tcp
chain = INPUT
action_ = %(banaction)s[name=%(__name__)s, port="%(port)s", protocol="%(protocol)s", chain="%(chain)s"]
action_mw = %(banaction)s[name=%(__name__)s, port="%(port)s", protocol="%(protocol)s", chain="%(chain)s"]
              %(mta)s-whois[name=%(__name__)s, dest="%(destemail)s", protocol="%(protocol)s", chain="%(chain)s", sendername="%(sendername)s"]
action_mwl = %(banaction)s[name=%(__name__)s, port="%(port)s", protocol="%(protocol)s", chain="%(chain)s"]
               %(mta)s-whois-lines[name=%(__name__)s, dest="%(destemail)s", logpath=%(logpath)s, chain="%(chain)s", sendername="%(sendername)s"]
action = %(action_)s

[ssh]
enabled  = true
port     = ssh
filter   = sshd
logpath  = /var/log/auth.log
maxretry = 6
```

| Variable    | Description |
| ----------- | ----------- |
| ignoreip    | can be a list of IP addresses, CIDR masks or DNS hosts. Fail2ban will not ban a host which matches an address in this list. Several addresses can be defined using space (and/or comma) separator.
| bantime     | the number of seconds that a host is banned.
| findtime, maxretry| a host is banned if it has generated "maxretry" during the last "findtime" seconds
| backend     | specifies the backend used to get files modification
| usedns      | specifies if jails should trust hostnames in logs, warn when DNS lookups are performed, or ignore all hostnames in logsyes:   if a hostname is encountered, a DNS lookup will be performed
| destemail   | destination email address used solely for the interpolations in jail.{conf,local,d/*} configuration files.
| sender      | sender email address used solely for some actions
| banaction   | default banning action (e.g. iptables, iptables-new, iptables-multiport, shorewall, etc) It is used to define a ction_* variables
| protocol    | default protocol (tcp, udp, ...)
| chain       | specify chain where jumps would need to be added in ban-actions expecting parameter chain
| enabled     | enables the jails
| port        | ports to be banned
| filter      | defines the filter to use by the jail
| logpath     | path to the logs

## Asterisk configuration

1. Copy the configuration file to the local one.
```
sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local
```

2. Add to <kbd>ignoreip</kbd> the addresses from which you are going to connect to the asterisk.

3. Add Asterisk jail (see below). You can set up variables however you like.

```
[asterisk]
enabled  = true
filter   = asterisk
backend  = auto
port     = 5060,5061
action   = iptables-allports[name=ASTERISK, protocol=all, blocktype=DROP]
logpath  = /var/log/asterisk/messages
findtime = 1m
maxretry = 5
bantime  = 30d
```

4. (optional) If you have ssh, it is more secure if you add it to the jail.

```
[sshd]
enabled  = true
bantime  = 60m
findtime = 1m
maxretry = 5
port     = ssh
logpath  = %(sshd_log)s
backend  = %(sshd_backend)s
```