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.

 

SYSTEM CONFIGURATION

General kacd configuration is done in the system configuration block. The system configuration block is defined using the keyword system, and an open brace begins the content of the system configuration. This is followed by system configuration statements, and the block ends with a closing brace.
system { system_configuration_statements }

 

CONFIGURATION STATEMENTS

debug [mask]4
The debug statement replicates the functionality of the -D and -d kacd commandline options. The presence of the debug keyword, with or without a following mask enables debug message output. The optional mask is a comma separated list of debug modules. Valid debug modules are route, pppoe, l2tp, radius, ppp, pppfsm, lcpfsm, ctrl, trace, pppd, system and parser. The special mask all enables debugging in all modules.

log_file filename
The log_file keyword replicates the functionality of the -o kacd commandline option. It redirects kacd output to the file indicated by the parameter filename, which must be enclosed in double quotes. The full directory path to the filename must already exist, kacd will not create directories.

 

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"

The proxy_auth statement

The proxy_auth statement sets a boolean flag to enable or disable proxy authentication if supported by the destination. If enabled, PPP authentication data is collected by kacd and sent to an L2TP peer in additional L2TP AVPs when the L2TP session is established. If not specified, proxy authentication is disabled.

proxy_auth "yes|no"

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 a combination of local configuration parameters in kacd and prol2tpd and RADIUS attributes. For any parameters specified in both the derived kacd/prol2tpd profile AND via a returned RADIUS attribute, the RADIUS value will be used.

MANDATORY

Tunnel-Type
Selects the destination endpoint protocol. Set to L2TP.

OPTIONAL

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.
Tunnel-Assignment-ID
Sets the tunnel name. If not set, the tunnel name is taken from the kacd profile, or Tunnel-Private-Group-ID value, else the string "default".
Tunnel-Server-Endpoint
Sets the IP address or FQDN of the tunnel destination server. If not set, this address is derived from the kacd profile or prol2tpd tunnel profile. If no address can be derived, the tunnel will not establish.
Tunnel-Client-Endpoint
Sets the IP address of the local interface to be used for the tunnel. This must be an IP address of an existing public interface of the LAC. The default is to let the system's routing tables determine the best interface to reach the L2TP tunnel peer address.
Tunnel-Password
Sets the password (shared secret) to be used when establishing the L2TP tunnel. If not set, the LAC will attempt to establish an unauthenticated L2TP tunnel.
Tunnel-Client-Auth-ID
Sets the advertised name when establishing the L2TP tunnel to the peer. This value is passed in L2TP control packets to the peer in the L2TP HostName AVP and may be used by the peer to match configured parameters of the requestor. If not set, the system's hostname is used.
Tunnel-Medium-Type
Selects the tunnel medium. This attribute tells kacd how to decode the address values given in Tunnel-Client-Endpoint and Tunnel-Server-Endpoint attributes. Currently only IPv4 is supported.
Katalix-Tx-Connect-Speed
Sets the transmit connect speed to use for the session. This is a Katalix vendor specific attribute: vendor 42620, attribute type 1.
Katalix-Rx-Connect-Speed
Sets the receive connect speed to use for the session. This is a Katalix vendor specific attribute: vendor 42620, attribute type 2.

 

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"
                proxy_auth on
                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
SYSTEM CONFIGURATION
CONFIGURATION STATEMENTS
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: 09:38:31 GMT, May 24, 2016