kacd.conf

 

NAME

kacd.conf - kacd configuration file  

SYNOPSIS

This document describes the configuration file syntax of the Katalix Access Concentration Daemon.  

DESCRIPTION

The kacd.conf file contains configuration information for kacd. Whitespace and newline characters are ignored. Comments may be included, they start with the # character, and end at the end of the line. Keywords are case sensitive and lowercase. The configuration consists of one or more route definitions. Strings may be quoted where they need to include  

ROUTE DEFINITION

Routes are defined using the keyword route, followed by a unique route name. An open brace begins the content of the route definition, the route source and destination definitions immediately follow, and the definition is ended by a closing brace. A route definition must include only one each of source and destination declarations, the order of which is unimportant.
route "name" { source_definition destination_definition }
 

SOURCE DEFINIITON

A source definition begins with the keyword source (or the abbreviation src), followed by a protocol name (see SOURCE PROTOCOLS below). An open brace begins the content of the source definition, followed by protocol specific statements, and ended by a closing brace.
source protocol { statement [ ... statement ] }
 

DESTINATION DEFINIITON

A destination definition begins with the keyword destination (or the abbreviation dst), followed by a protocol name (see DESTINATION PROTOCOLS below). An open brace begins the content of the destination definition, followed by protocol specific statements, and ended by a closing brace.
destination protocol { statement [ ... statement ] }
 

SOURCE PROTOCOLS

 

PPPoE

A PPPoE source definition uses the protocol keyword pppoe. The following statements are used within a PPPoE source definition to control client's access to services:

The interface statement

Specifies the ethernet interface on which to listen for PPPoE session requests, one and only one interface is required per PPPoE source definition.

interface "interface_name"

The service_name statement

PPPoE client service requests include a service name, service_name statements specify which requests will be granted. At least one service_name statement is required in a PPPoE source definition, multiple service_name statements are permitted.

service_name any

Indicates that service should be provided to any client requesting it, regardless of the service name they request. When kacd responds to a PPPoE service request as a result of this statement, the service name that is returned to the client will match the one they requested. This prevents clients from trying different service names in order to establish what services the access concentrator provides.

service_name advertised "name"

Indicates that kacd should advertise to clients that service name is provided by this access concentrator. Service will be provided to any client which requests a service with this name.

service_name private "name"

Indicates that kacd should provide service to clients which request a service named name. The service name will not be advertised to clients who request a list of services this access concentrator provides.

Multiple routes may offer service on the same ethernet interface. In this case, kacd will attempt to match the service name requested to an advertised or private service_name statement before resorting to providing service under a service_name any statement.

To avoid a routing conflict, only one route may offer to provide service with the service_name any on any particular ethernet interface.  

DESTINATION PROTOCOLS

 

L2TP

An L2TP destination definition uses the protocol keyword l2tp. The kacd daemon will establish a new L2TP session within an L2TP tunnel for each successfully negotiated route source connection. The following statements are used within an L2TP destination definition to control session and tunnel creation:

The tunnel_name statement

Specifies the name to give to the tunnel which will be established (if it isn't already opened) as the destination for this route.

tunnel_name "name"

The tunnel_profile statement

Specifies the prol2tpd tunnel profile name which contains the parameters of the tunnel which kacd will establish as the destination for this route. All tunnel configuration must be done via prol2tpd profiles.

tunnel_profile "name"

The peer_address statement

This statement sets the address (IP address or fully qualified domain name) of the L2TP peer to which the tunnel should be established.

peer_address "address"
 

RADIUS

A RADIUS destination definition uses the protocol keyword radius. The final destination endpoint of a RADIUS route is discovered by kacd using the RADIUS protocol.

A RADIUS destination consists of RADIUS configuration statements and one or more server definitions:

destination radius { [ statements ... ] server_definition [ ... server_definition ] }

CONFIGURATION STATEMENTS

The ppp_auth_protocols statement

The ppp_auth_protocols statement is a comma-separated quoted list of the authentication protocols to be negotiated with PPPoE clients during LCP. This list should match the authentication protocols offered by RADIUS servers within the enclosing RADIUS destination definition. Supported authentication types are "pap", "chap" and "eap". If not specified kacd defaults to offering all protocols (equivalent to ppp_auth_protocols "pap,chap,eap")

ppp_auth_protocols "auth_protocol_list"

SERVER DEFINITION

This defines one of the group of RADIUS servers to contact for destination endpoint parameters. The server definition begins with the keyword server followed by the address (IP address or fully qualified domain name) of the RADIUS server. An open brace begins the content of the server definition, followed by further RADIUS server statements, and is ended by a closing brace.

server "address" { statement [ ... statement ] }

The secret statement

The secret statement specifies the shared secret to use when contacting this RADIUS server. The secret statement is mandatory.

secret "secret"

The retries statement

The retries statement sets the number of times kacd should retry an attempt to contact a RADIUS server before giving up. If this statement is not present, the default number of retries is 2 (i.e.: a total of 3 attempts to contact the server).

retries retries

The timeout statement

The timeout statement specifies the number of seconds that kacd should wait for a response from a RADIUS server. If this statement is not present, the default is to wait for 5 seconds.

timeout seconds

The port statement

The port statement sets the UDP port number to use when contacting the RADIUS server for authentication. Valid values are numbers in the range 1 to 65535. The default value if not specified is 1812.

port number

 

RADIUS server configuration

When using a RADIUS server to provide the parameters of a route destination, certain RADIUS attributes must be returned so that kacd can open the destination endpoint. The following attributes should be set in the RADIUS server configuration.

 

MANDATORY

Tunnel-Type
Selects the destination endpoint protocol. Currently only L2TP is supported.
Tunnel-Medium-Type
Selects the tunnel medium. Currently only IPv4 is supported.
Tunnel-Server-Endpoint
Sets the IP address or FQDN of the tunnel destination server.
Tunnel-Private-Group-ID
Must be the name of the prol2tpd tunnel profile which will be used.

 

OPTIONAL

Tunnel-Assignment-ID
Sets the tunnel name.

 

ACCESS CONTROL LISTS

To protect against denial of service attacks (DoS), kacd implements access control lists. One access control definition may be included within a source definition. Access control definitons begin with either the allow or the deny keyword. An open brace begins the content of the control list, followed by one or more list entries and the definition is ended with a closing brace. Lists defined with the allow keyword cause kacd to deny access to any clients which don't match one of the following list entries. Lists defined with the deny keyword cause kacd to deny access to any clients which match one of the following list entries.
allow { list_entry [ ... list_entry ] }
deny { list_entry [ ... list_entry ] }
The syntax of the list_entry is dependent on the protocol of the route source.
 

PPPoE

Access control list entries for PPPoE sources contain the ethernet MAC addresses of the clients to allow/deny access to, for example:
allow { "12:34:56:78:9A:BC" "23:45:67:89:AB:CD" }
Access control lists can also be modified at runtime using the kac_manage utility, see it's manpage for details.
 

EXAMPLES


route "public clients" {
        source pppoe {
                interface "eth0"
                service_name any
                deny {
                        "12:34:56:78:9A:BC"
                        "23:45:67:89:AB:CD"
                }
        }
        destination l2tp {
                tunnel_name "public tunnel"
                tunnel_profile "public"
                peer_address "192.168.1.100"
        }
}

route "private clients" {
        source pppoe {
                interface "eth0"
                service_name private "restricted"
                service_name private "private"
        }
        destination l2tp {
                tunnel_name "private tunnel"
                tunnel_profile "private"
                peer_address "privatel2tp.example.com"
        }
}

route "dynamic clients" {
        source pppoe {
                interface "eth0"
                service_name private "dynamic"
        }
        destination radius {
                ppp_auth_protocols "chap,eap"
                server "radiusauth.example.com" {
                        secret "terces 321"
                        timeout 10
                        port 7777
                }
        }
}

A PPPoE client connection on eth0 which requests a service name other than 'restricted' or 'private' will use the 'public clients' route. kacd will open a session inside the tunnel 'public tunnel' to the peer at 192.168.1.100 and forward all PPPoE session packets to the peer over that session. If the tunnel 'public tunnel' does not already exist, kacd will ask prol2tpd to create it using the prol2tpd tunnel profile named 'public'.

A PPPoE client which requested the service name 'restricted' or 'private' will instead be forwarded down a session created by kacd on the tunnel 'private tunnel' to the peer privatel2tp.example.com. If the tunnel 'private tunnel' does not already exist, kacd will ask prol2tpd to create it using the prol2tpd tunnel profile named 'private'.

A PPPoE client requesting the service name 'dynamic' will perform initial LCP negotiation with kacd itself, which will offer CHAP or EAP authentication. This will cause kacd to contact the RADIUS server radiusauth.example.com on port 7777 with the PPPoE client's authentication parameters. The RADIUS server may then accept or decline to authenticate the user. If authenticated, it will return RADIUS attributes sufficient to enable kacd to negotiate the tunnel endpoint for the incoming PPPoE session. It will then open this tunnel and connect the incoming PPPoE client session to the tunnel, the PPP peer at the far end of this tunnel will then restart PPP LCP negotiation with the PPPoE client.  

SEE ALSO


kacd(8), kac_info(8), kac_trace(8), kac_manage(8),


 

Index

NAME
SYNOPSIS
DESCRIPTION
ROUTE DEFINITION
SOURCE DEFINIITON
DESTINATION DEFINIITON
SOURCE PROTOCOLS
PPPoE
DESTINATION PROTOCOLS
L2TP
RADIUS
RADIUS server configuration
MANDATORY
OPTIONAL
ACCESS CONTROL LISTS
PPPoE
EXAMPLES
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 14:23:21 GMT, June 03, 2013