Call Us Today! 877.742.2583




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

About

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

Definitions

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

Rules

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}"/>

Overlapping

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

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

will win over

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

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">
  <network-lists>
    <list name="test1" default="deny">
      <node type="allow" cidr="1.2.3.0/24"/>
    </list>
  </network-lists>
</configuration>

Sample deny

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

Overview

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

apply-inbound-acl

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".

apply-register-acl

Allow users to register from a particular cidr without authenticating.

apply-proxy-acl

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.

apply-candidate-acl

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

auth-calls

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="12.34.56.78/32,20.0.0.0/8">

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

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

Used in conjunction with auth-calls.

Notes

FreeSWITCH automatically makes a few ACLs, namely:

  1. rfc1918.auto - RFC 1918 Space.
  2. nat.auto - RFC 1918 Excluding your local lan.
  3. localnet.auto - ACL for your local lan.
  4. 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.

Users

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}"/>
  </list>

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
<include>
  <user id="1000" cidr="12.34.56.78/32,20.0.0.0/8">
    <params>
      <param name="password" value="1234"/>
      <param name="vm-password" value="1000"/>
    </params>
    <variables>
      <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"/>
    </variables>
  </user>
</include>

 

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="1.2.3.0/8"/>

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

Example:

<include>
  <user id="1000" number-alias="1000">
    <params>
      <param name="password" value="1234"/>
      <param name="vm-password" value="1000"/>
      <param name="auth-acl" value="1.2.3.0/8"/>
    </params>
    <variables>
      <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"/>
    </variables>
  </user>
</include>

 

 

Services

Event Socket

See Event Socket

Sofia

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

check_acl

See mod_dptools: check_acl

API Commands

reloadacl

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

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:

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"/>
  </condition>
</extension>