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, and zero or more profile definitions. Strings may be quoted where they need to include spaces.  

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 }
 

PROFILE DEFINITION

Profiles are used to contain a destination definition so that it may be referred to by name. A profile is defined using the keyword profile, followed by a unique profile name. An open brace begins the content of the profile definition, the profile destination definition follows, and the definition is ended by a closing brace. A profile definition must contain exactly one destination declaration.
profile "name" { 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"
 

PPPD

A PPPD destination definition uses the protocol keyword pppd. The kacd daemon will fork a new pppd process to handle the incoming PPPoE session. The following statements are used within a PPPD destination definition to configure the pppd process which is started.

The options_file statement

Specifies the path to the options file which will be passed directly through to the new pppd instance using the pppd parameter file. All other pppd configuration must be done via the options file.

options_file "path"

 

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 required destination endpoint. Depending on the RADIUS attributes returned, kacd is able to route to either L2TP or PPPD destinations.

 

L2TP ATTRIBUTES

To configure an L2TP destination, the following attributes should be set in the RADIUS server configuration. It is possible to specify all of the required L2TP parameters via RADIUS attributes, or to use

MANDATORY

Tunnel-Type
Selects the destination endpoint protocol. Set to L2TP.
Tunnel-Medium-Type
Selects the tunnel medium. Currently only IPv4 is supported.
Tunnel-Private-Group-ID
If Tunnel-Server-Endpoint is also specified, this attribute is interpreted as the prol2tpd tunnel profile name to be used to create the tunnel.
If Tunnel-Server-Endpoint is not specified, then this attribute is interpreted as a kacd profile name, and the tunnel parameters will be derived from that profile. For any parameters specified in both the derived kacd profile AND via a returned RADIUS attribute, the RADIUS value will be used.

OPTIONAL

Tunnel-Assignment-ID
Sets the tunnel name.
Tunnel-Server-Endpoint
Sets the IP address or FQDN of the tunnel destination server.

 

PPPD ATTRIBUTES

To configure a PPPD destination, it is necessary to define a profile with a PPPD destination definition (see PROFILE DEFINITION above). This profile will be used to configure the pppd session, and is selected by the Framed-Route attribute.

The following attributes should be set in the RADIUS server configuration to indicate to kacd that it should terminate an incoming session with a local pppd instance.

MANDATORY

Framed-Protocol
Selects the destination endpoint protocol. Set to PPP.
Framed-Route
Selects the kacd profile name, the destination parameters will be derived from that profile.

OPTIONAL

Framed-IP-Address
Gives the IP address to be passed to pppd to use as the remote IP address for the PPP session. This is passed via the pppd commandline as ":<remote-ip-address>", the IP address to be used for the local IP address should be configured via the pppd options file as "<local-ip-address>:".

 

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

profile "radius_pppd" {
        destination pppd {
                options_file "/etc/ppp/options.radius"
        }
}

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

route "management" {
        source pppoe {
                interface "eth1"
                service_name any
        }
        destination pppd {
                options_file "/etc/ppp/options.management"
        }
}

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 endpoint for the incoming PPPoE session. It will then open the destination endpoint and connect the incoming PPPoE client session to it.

All PPPoE clients requesting service on 'eth1' will be terminated in a local pppd instance, the options to be passed to this pppd instance will be read from the file '/etc/ppp/options.management'. IP addresses and authentication parameters are configured in this external options file.  

SEE ALSO


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


 

Index

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

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