Call Us Today! 877.742.2583

Page tree
Skip to end of metadata
Go to start of metadata


A.C.L. stands for Access Control List and is a list of permissions associated with an object. The list defines what network entities are allowed to access the object.

 Click here to expand Table of Contents


Access Control Lists are named and defined in autoload_configs/acl.conf.xml


Import from domain users

If your domain's users (in directory/default/*.xml) have cidr attributes, you can import them into any ACL list

<node type="allow" domain="$${domain}"/>


In the case of overlapping lists, the more specific of the nodes will take precedence.

<node type="allow" cidr=""/>

will win over

<node type="deny" cidr=""/>

in the same list

Allow or Deny

The highest priority rules are the most specific, the lowest priority are the least specific. A node rule will override a list default.

Example Lists

Sample allow

allows access from anyone on 1.2.3.*
<configuration name="acl.conf" description="Network Lists">
    <list name="test1" default="deny">
      <node type="allow" cidr=""/>

Sample deny

allows access from anyone except 4.3.2.*
<configuration name="acl.conf" description="Network Lists">
    <list name="test2" default="allow">
      <node type="deny" host="" mask=""/>


Access control lists may be applied in the sip_profile, via the Event Socket Layer from a script, or in a dialplan application.

sip_profile settings

These Access Control Lists are named in autoload_configs/acl.conf.xml and applied in sip_profiles/internal.xml and sip_profiles/external.xml


Allow users to make calls from a particular cidr without authenticating

Usage: <param name="apply-inbound-acl" value="<list name>"/>

<list name> is set in acl.conf.xml and defines the subnet that will be processed by the ACL bearing this name. The default name is "domains".


Allow users to register from a particular cidr without authenticating.


Use the IP specified in X-AUTH-IP header sent from proxy for apply-inbound-acl Note: You'll need to configure your proxy to add this header.


ICE candidates for RTP transport are checked against this list. It defaults to if unset, which excludes the LAN.


Can be set to true/false forcing users to authenticate or no on the profile. Only allow users from a specific cidr to register/make calls. Note: Currently auth-calls does not work with registrations/invites through a proxy. You'll need to do this inside your xml_curl directory scripts or on your proxy.

Directory settings:

<user id="1000" number-alias="1000" cidr=",">

Used with in conjunction with apply-inbound-acl and apply-register-acl.

<param name="auth-acl" value=""/>

Used in conjunction with auth-calls.


FreeSWITCH automatically makes a few ACLs, namely:

  1. - RFC 1918 Space.
  2. - RFC 1918 Excluding your local lan.
  3. - ACL for your local lan.
  4. - ACL for your local lan.

Note that you can use these auto generated ACLs by first activating them in sip_profiles:

<param name="local-network-acl" value=""/>
<param name="apply-inbound-acl" value=""/>

& then using them. For example in acl.conf.xml:

<list name="" default="allow">
  <node type="allow" cidr="41.XXX.XXX.XXX/29"/>

IPv6 ACL definitions are only supported in FreeSWITCH vesion 1.0.7 and later.

local-network-acl doesn't interfere or authenticate any calls by default like any of the other apply ACL, it just defines the local network. If you use the internal profile on a public IP which accepts calls from other servers then it doesn't hurt leaving it at The best way to prevent unauthorized calls is using a firewall.


It is possible to automatically add users with a CIDR attribute to an ACL list. This is particularly useful for authenticating people by static IP address instead of using challenge authentication.

First of all, make sure you have the following in acl.conf.xml (the Vanilla config does)

  <list name="domains" default="deny">
    <node type="allow" domain="$${domain}"/>

The node element with the 'domain' attribute tells the ACL module to look into that FS domain to insert ACL entries. If you have a multi-domain (multiple tenant) machine, make sure you add node elements for all your domains.

The next step is creating a user with the CIDR attribute. You can separate multiple CIDRs with a comma.

User directory entry with CIDR
  <user id="1000" cidr=",">
      <param name="password" value="1234"/>
      <param name="vm-password" value="1000"/>
      <variable name="accountcode" value="1000"/>
      <variable name="user_context" value="default"/>
      <variable name="effective_caller_id_name" value="Extension 1000"/>
      <variable name="effective_caller_id_number" value="1000"/>


The last step is to verify that your channel driver has been instructed to use this ACL. For Sofia, you should see the following line in your sip_profile (as noted above):

 <param name="apply-inbound-acl" value="domains"/>


Additionally, you can restrict a user to a predefined CIDR without allowing the whole CIDR block.

Users in the directory can have "auth-acl" parameters applied to them so as to restrict that user's access to a predefined ACL or a CIDR.

  <param name="auth-acl" value=""/>

Note: this will require "auth-calls" to be set to true in your sip (sofia) profile.


  <user id="1000" number-alias="1000">
      <param name="password" value="1234"/>
      <param name="vm-password" value="1000"/>
      <param name="auth-acl" value=""/>
      <variable name="accountcode" value="1000"/>
      <variable name="user_context" value="default"/>
      <variable name="effective_caller_id_name" value="Extension 1000"/>
      <variable name="effective_caller_id_number" value="1000"/>




Event Socket

See Event Socket


See Sofia

Sofia SIP profiles

In your SIP (Sofia) profiles, you can use the following lines to apply the ACL setting to incoming request for either REGISTERs or INVITEs (or both).

  <param name="apply-inbound-acl" value="<acl_list|cidr>"/>
  <param name="apply-register-acl" value="<acl_list|cidr>"/>

More than one ACL can be defined, in that case all the ACLs will be tested and the message will be rejected if any of the ACLs fail (within an acl_list the test is an OR, with multiple params the test is an AND of all the ACLs)

Phones having IPs within these ACLs will be able to perform calls (apply-inbound-acl) or register (apply-register-acl) without having to provide a password (i.e. without getting a "401 Unauthorized" challenge message).

Those ACLs do not block any traffic. Should you want to protect your FreeSWITCH installation from being contacted by some IP addresses, you will need to setup some firewall rules. To protect your installation, you can look at QoS

Should you want to allow everyone to call your FreeSWITCH installation but restrict outgoing calls, this should be done in the dialplan see mod_dptools: respond.

The ACL behavior is modified by auth-calls, accept-blind-reg, and accept-blind-auth.

You can also specify a C-style ternary test <list name>:<pass context>:<fail context> for apply-inbound-acl.

Dialplan Apps


See mod_dptools: check_acl

API Commands


reloadacl [<reloadxml>]

freeswitch@internal> reloadacl reloadxml

If you've made a change in acl.conf.xml, you can run 'reloadacl reloadxml' in order to avoid restarting FreeSWITCH and your new change will be effective.

Commands reloadxml and reloadacl do not load new lists. You must restart FreeSWITCH to recognize the newly added ACL name.



acl <ip> <list|net>

This command will allow you to test an IP address against one of your ACLs. Will return true or false. Use it to validate that your ACL behaves as expected. This test can also be a part of a dialplan <condition> test.

  freeswitch@mybox> acl
  freeswitch@mybox> acl list_foo

For the second line, 'list_foo' refers to the <list name=> that you specified in acl.conf.xml. When you change acl.conf.xml you must restart the FreeSWITCH process. Commands reloadxml and reloadacl do not load new lists.

Routing using ACL can be accomplished using the acl command. For example, if you want to pass calls for hosts in list_foo ACL:

Dialplan condition using ACL
<extension name="foo-hosts-calls">
  <condition field="${acl(${network_addr} list_foo)}" expression="true"/>
  <condition field="destination_number" expression="(.*)">
    <action application="bridge" data="sofia/switchbox/$1@x.x.x.x:5060"/>