ACL 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.
There are ACLs automatically created on startup (see below), and one can define additional lists in
The default configuration file from the vanilla configuration: (TODO: link to a configuration page for <conf_dir>)
Automatically defined ACLs
|RFC1918, excluding your local LAN|
|ACL for your local LAN|
|ACL for your local LAN|
Sample usage in mod_event_socket
The more specific the rule, the higher priority it gets (i.e., more specific > least specific).
Import from domain users
If your domain's users (usually in
cidr attributes (see XML User Directory), you can import them into any ACL list.
In the case of overlapping
lists, the more specific nodes will take precedence.
NODE A will win over
NODE B in the same list below.
Allow or Deny
A node rule will override the
default attribute of a
Access control lists may be applied in
- SIP profiles, via the Event Socket Layer from a script, or in a dialplan application
- where else?
stop-on-bind-errorfor example seems specific only to
mod_erlang_event(at least, the name only pops up in their source), and the same goes to
auth-callsthat is seemingly specific to
sip_profile settings (see
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 wan.auto 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.
<user id="1000" number-alias="1000" cidr="220.127.116.11/32,18.104.22.168/8">
Used with in conjunction with apply-inbound-acl and apply-register-acl.
<param name="auth-acl" value="22.214.171.124/8"/>
Used in conjunction with auth-calls.
event_socket.conf.xml parameters (for
From the vanilla event_socket.conf.xml. Where is it documented?
FreeSWITCH automatically makes a few ACLs, namely:
- rfc1918.auto - RFC 1918 Space.
- nat.auto - RFC 1918 Excluding your local lan.
- localnet.auto - ACL for your local lan.
- loopback.auto - 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="localnet.auto"/> <param name="apply-inbound-acl" value="localnet.auto"/>
& then using them. For example in acl.conf.xml:
<list name="localnet.auto" default="allow"> <node type="allow" cidr="41.XXX.XXX.XXX/29"/> </list>
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 localnet.auto. 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)
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.
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="126.96.36.199/8"/>
Note: this will require "auth-calls" to be set to true in your sip (sofia) profile.
See Event Socket
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
You can also specify a C-style ternary test <list name>:<pass context>:<fail context> for
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 192.168.42.42 192.168.42.0/24 freeswitch@mybox> acl 192.168.42.42 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: