Advanced Configurations

This section offers a detailed guide to configuring FreeSWITCH, including advanced features and functionalities.

When configuring FreeSWITCH, there are certain configurations that apply universally to anyone using the platform, and some that are more specialized for particular features like ACL (Access Control Lists), WebRTC (mod_verto) and other. Below is a breakdown of the theoretical configuration steps required for both:

ACL Configuration (Access Control List)
WebRTC Configuration (mod_verto)

warning

This guide assumes you have a foundational understanding of FreeSWITCH and have completed the Basic FreeSWITCH configuration.

ACL Configuration (Access Control List)

ACLs in FreeSWITCH are used to control access to the system, primarily to secure against unauthorized IPs or domains. These are essential for securing your system, as they allow you to restrict which IP addresses can communicate with your FreeSWITCH instance.

Steps for ACL Configuration

Define ACLs in acl.conf.xml:

This file is located in the FreeSWITCH configuration directory (/etc/freeswitch/autoload_configs/acl.conf.xml).
You need to define IP ranges or specific IPs that are allowed or denied.

Example ACL definition:

<configuration name="acl.conf" description="Network Lists">

<network-lists>
  <!--
  These ACL's are automatically created on startup.

  rfc1918.auto  - RFC1918 Space
  nat.auto      - RFC1918 Excluding your local lan.
  localnet.auto - ACL for your local lan.
  loopback.auto - ACL for your local lan.
  -->

  <list name="allowed_networks" default="deny">
    <node type="allow" cidr="192.168.1.0/24"/> <!-- Allowing a specific subnet -->
    <node type="allow" cidr="203.0.113.5/32"/> <!-- Allowing a specific IP -->
  </list>

  <list name="domains" default="deny">
    <!-- domain= is special it scans the domain from the directory to build the ACL -->
    <node type="allow" domain="$${domain}"/>
    <!-- use cidr= if you wish to allow ip ranges to this domains acl. -->
    <!-- <node type="allow" cidr="192.168.0.0/24"/> -->
  </list>
</network-lists>

</configuration>

In this example, allowed_networks list is created with a default policy of deny, but it allows IPs from the 192.168.1.0/24 subnet and the specific IP 203.0.113.5.

Apply ACL to SIP Profile in internal.xml or external.xml: After defining the ACL, you need to bind it to your SIP profiles (e.g., internal or external profiles) to enforce access control.

Open your SIP profile configuration file (/etc/freeswitch/sip_profiles/internal.xml or external.xml), and add/update the following:
```
<param name="apply-inbound-acl" value="allowed_networks"/>
```
This binds the allowed_networks ACL to the SIP profile, ensuring that only IPs defined in the allowed_networks list can register or make calls.
Reload ACL Configurations: After editing the ACL configuration, reload the module or the configuration for the changes to take effect:
```
fs_cli -x "reloadacl"
```
This ensures the ACL changes are applied without needing to restart FreeSWITCH.

tip
To ensure that all ACL configuration changes are properly applied and to avoid potential issues, it is recommended to restart FreeSWITCH after making any modifications. This helps incorporate all updates and maintain system stability. Alternatively, you can use reloadacl CLI command to refresh ACL at runtime.

WebRTC Configuration (mod_verto)

WebRTC in FreeSWITCH is mainly handled via the mod_verto module. mod_verto is the signaling mechanism for WebRTC and requires configuring various components, such as secure transport (wss), codecs, and session handling.

Steps for WebRTC Configuration (mod_verto)

Enable mod_verto Module: Ensure that mod_verto is installed and loaded. In modules.conf.xml, ensure the following is present:
```
<load module="mod_verto"/>
```

Configure WebSocket Profile for WebRTC (verto.conf.xml): The verto.conf.xml file contains the basic configuration for WebRTC signaling over WebSocket. It is located in /etc/freeswitch/autoload_configs/verto.conf.xml.

Example configuration:

 <configuration name="verto.conf" description="HTML5 Verto Endpoint">

 <settings>
   <param name="debug" value="10"/>
   <!-- <param name="kslog" value="true"/> -->
   <!-- seconds to wait before hanging up a disconnected channel -->
   <param name="detach-timeout-sec" value="1"/>
   <!-- enable broadcasting all FreeSWITCH events in Verto -->
   <!-- <param name="enable-fs-events" value="false"/> -->
   <!-- enable broadcasting FreeSWITCH presence events in Verto -->
   <!-- <param name="enable-presence" value="true"/> -->
 </settings>

 <profiles>
   <profile name="default-v4">
     <param name="bind-local" value="127.0.0.1:2318"/>
     <param name="bind-local" value="$${local_ip_v4}:8082" secure="true"/>
     <param name="force-register-domain" value=""/>
     <param name="secure-combined" value="$${certs_dir}/wss.pem"/>
     <param name="secure-chain" value="$${certs_dir}/wss.pem"/>
     <param name="userauth" value="true"/>
     <!-- setting this to true will allow anyone to register even with no account so use with care -->
     <param name="blind-reg" value="true"/>
     <param name="mcast-ip" value="224.1.1.1"/>
     <param name="mcast-port" value="1337"/>
     <param name="rtp-ip" value="$${local_ip_v4}"/>
     <param name="ext-rtp-ip" value="$${external_rtp_ip}"/>
     <param name="local-network" value="localnet.auto"/>
     <param name="outbound-codec-string" value="OPUS,PCMU,PCMA"/>
     <param name="inbound-codec-string" value="OPUS,PCMU,PCMA"/>
     <param name="context" value="webrtc"/>
     <param name="dialplan" value="XML"/>
     <param name="apply-nat-acl" value="nat.auto"/>
     <param name="local-network-acl" value="nat.auto"/>
     <param name="apply-candidate-acl" value="nat.auto" />
     <param name="apply-candidate-acl" value="wan.auto" />
     <param name="timer-name" value="soft"/>
   </profile>

   <profile name="default-v6">
     <param name="bind-local" value="[$${local_ip_v6}]:8081"/>
     <param name="bind-local" value="[$${local_ip_v6}]:8082" secure="true"/>
     <param name="force-register-domain" value="$${domain}"/>
     <param name="secure-combined" value="$${certs_dir}/wss.pem"/>
     <param name="secure-chain" value="$${certs_dir}/wss.pem"/>
     <param name="userauth" value="true"/>
     <!-- setting this to true will allow anyone to register even with no account so use with care -->
     <param name="blind-reg" value="false"/>
     <param name="rtp-ip" value="$${local_ip_v6}"/>
     <!--  <param name="ext-rtp-ip" value=""/> -->
     <param name="outbound-codec-string" value="opus,h264,vp8"/>
     <param name="inbound-codec-string" value="opus,h264,vp8"/>
     <param name="context" value="webrtc"/>
     <param name="dialplan" value="XML"/>
     <param name="apply-candidate-acl" value="ws-client"/>
     <param name="apply-candidate-acl" value="wan_v6.auto"/>
     <param name="apply-candidate-acl" value="rfc1918.auto"/>
     <param name="apply-candidate-acl" value="any_v6.auto"/>
     <param name="apply-candidate-acl" value="wan_v4.auto"/>
     <param name="apply-candidate-acl" value="any_v4.auto"/>
     <param name="timer-name" value="soft"/>
   </profile>
 </profiles>

 </configuration>

Breakdown of Key Elements:

WebSocket Binding:
- Unsecure WebSocket: Bound to port 2318 (127.0.0.1:2318). This is the unsecure WebSocket for non-TLS connections.
- Secure WebSocket: Bound to port 8082 ($${local_ip_v4}:8082) with TLS enabled (secure="true").
TLS Certificates:
- secure-combined and secure-chain parameters point to the wss.pem file that includes your TLS certificates required for secure WebSocket connections (WSS).
RTP Configuration:
- rtp-ip: Local IP for handling RTP streams.
- ext-rtp-ip: The external IP address (or use of STUN server) for NAT traversal in media connections.
Codecs:
- opus, pcmu, and pcma are common codecs for WebRTC (audio). Ensure these codecs are enabled to guarantee compatibility with WebRTC clients.
Dialplan and Context:
- context: Specifies the dialplan context where calls from mod_verto will be routed. Typically, you will want this to point to a context set up for WebRTC users.
- dialplan: Specifies that the FreeSWITCH XML dialplan will be used.
Access Control Lists (ACL):
- apply-candidate-acl: ICE candidates for RTP transport are checked against this list. It defaults to wan.auto if unset, which excludes the LAN. In other words, it limits which IP ranges or networks can establish WebRTC sessions with your server. Some of the typical ACLs used here are:
  - ws-client: Allows WebSocket clients from ACL list.
  - localnet.auto: Automatically applies rules for local network ranges.
  - wan_v4.auto: Detects WAN IPv4 addresses for proper handling.
  - rfc1918.auto: Allows private IP addresses (e.g., 192.168.x.x, 10.x.x.x).
  - any_v4.auto: Allows any IPv4 address, if necessary.
  - nat.auto: Allow auto NAT to incoming SDP ICE candidates
  - wan.auto: Exclude all LAN networks.
Timers for WebRTC:
- The timer-name="soft" setting is often used for WebRTC to ensure smooth media handling. The soft timer allows the server to handle media timing in software, which is ideal for WebRTC scenarios.

Considerations

Blind Registration: The blind-reg parameter is set to true, which allows anyone to register without providing credentials. This should be used with caution as it could expose your system to unauthorized users.
User Authentication: The userauth parameter is set to true means FreeSWITCH requires that WebRTC clients authenticate themselves before they can establish a connection. This means that clients need to provide valid credentials (username and password) to connect to the server and make or receive calls.
Secure WebSocket (WSS): Ensure that the certificate in wss.pem is trusted by browsers (e.g., from a recognized CA or properly signed if self-signed).
NAT Traversal: Make sure that your external RTP IP is correctly set, especially when dealing with clients behind NAT. You may also want to configure ICE/STUN servers if necessary.

warning

Ensure proper configuration of the context and dialplan parameters to handle WebRTC calls effectively. The context parameter specifies the dialplan context that will manage WebRTC calls, while the dialplan parameter determines the format and routing rules used for these calls.

By applying these configurations, you should be able to support WebRTC clients using the mod_verto module, ensuring secure signaling (WSS) and optimized media handling. For a comprehensive and detailed guide on mod_verto configuration, refer to the official nod_verto Configuration docs.

ACL Configuration (Access Control List)​

Steps for ACL Configuration​

WebRTC Configuration (mod_verto)​

Steps for WebRTC Configuration (mod_verto)​

Considerations​

ACL Configuration (Access Control List)

Steps for ACL Configuration

WebRTC Configuration (mod_verto)

Steps for WebRTC Configuration (mod_verto)

Considerations