ACL

From FreeSWITCH Wiki
(Redirected from Acl)
Jump to: navigation, search
Warning

Superseded by Confluence

 


Contents

ACL

ACL stands for Access Control List and is a list of permissions associated with an object. The list shows who or what is allowed to access the object.

Configuration

Define the names of access control lists, their permissions, and the subnets that they control in acl.conf.xml

Overview

SIP profile settings:

apply-inbound-acl 

Allow users to make calls from a particular cidr without authenticating

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

auth-calls 

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.

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 default 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 domain to insert ACL entries. If you have a multi-domain 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.

<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 your channel driver has instruction to use this ACL. For Sofia, you should see the following line in your profile:

 <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 users 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 ACL will be tested and the message will be rejected if any of the ACL fails (within an acl_list the test is an OR, with multiple param the test is an AND)

Phones with 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 Misc._Dialplan_Tools_respond.

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

With recent git, you can now specify <list name>:<pass context>:<fail context> for apply-inbound-acl

Apps

check_acl

This dialplan function will allow you to check an ACL and route by it.

check_acl <ip> <acl | cidr> [<hangup_cause>]

hangup_cause defaults to rejected (see Hangup Causes)

<action application="check_acl" data="${network_addr} foo normal_clearing"/>
<action application="check_acl" data="${network_addr} 1.2.3.0/8 normal_clearing"/>

This application may also be run inline from the XML dialplan.

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 process and your new change will be effective.

acl

acl <ip> <list|net>

This command will allow you to test an IP address against one of your ACL's. Will return true or false. Use it to validate that your ACL behaves as expected.

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 specify 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:

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