README.md

freeradius

Table of Contents

1. Overview
2. Module Description - What the module does and why it is useful
3. Usage - Configuration options and additional functionality
   • Classes
     • freeradius
     • freeradius::status_server
     • freeradius::control_socket
   • Resources
     • freeradius::attr
     • freeradius::blank
     • freeradius::cert
     • freeradius::client
     • freeradius::config
     • freeradius::dictionary
     • freeradius::home_server
     • freeradius::home_server_pool
     • freeradius::instantiate
     • freeradius::ldap
     • freeradius::module::ldap
     • freeradius::krb5
     • freeradius::module
     • freeradius::module::ippool
     • freeradius::module::linelog
     • freeradius::module::detail
     • freeradius::module::files
     • freeradius::module::eap
     • freeradius::module::preprocess
     • freeradius::module::huntgroup
     • freeradius::policy
     • freeradius::realm
     • freeradius::site
     • freeradius::sql
     • freeradius::statusclient
     • freeradius::template
     • freeradius::virtual_module
4. Limitations - OS compatibility, etc.
5. Development - Guide for contributing to the module

Overview

This module installs and configures FreeRADIUS server on Linux. It supports FreeRADIUS 3.x only. It was designed with CentOS in mind but should work on other distributions.

This module requires Puppet 4.0.0 or greater. Puppet 3.x was discontinued at the end of 2016.

jgazeley/freeradius	FreeRADIUS
3.x	3.x
2.x	3.x
1.x	2.x and 3.x
0.x	2.x

Module Description

This module installs FreeRADIUS from a distro-provided package and installs a number of customised config files to enable flexibility. It then provides some helpers to allow you to easily configure virtual servers (sites), modules, clients and other config items. Most of these items accept a flat config file which you supply either as a static file or a template - similar to the source and content parameters in Puppet's file resource.

This module is designed to make it more straightforward for RADIUS administrators to deploy RADIUS servers using Puppet. This module does not serve as a wizard and does not avoid having to have an understanding of FreeRADIUS.

Usage

This module provides several classes and defined types which take parameters.

Classes

freeradius

The freeradius class installs the base server. In the early releases, this class does not have many parameters as most values are hard-coded. I am working on parameterising more of the global settings to increase flexibility. Patches are welcome.

control_socket

Use of the control_socket parameter in the freeradius class is deprecated. Use the freeradius::control_socket class instead.

correct_escapes

Use correct backslash escaping in unlang. Default: true

max_requests

The maximum number of requests which the server keeps track of. This should be 256 multiplied by the number of clients. Default: 4096

max_servers

Limit on the total number of servers running. Default: 4096

mysql_support

Install support for MySQL. Note this only installs the package. Use freeradius::sql to configure SQL support. Default: false

perl_support

Install support for Perl. Default: false

preserve_mods

Leave recommended stock modules enabled. Default: true

utils_support

Install FreeRADIUS utils. Default: false

ldap_support

Install support for LDAP. Default: false

dhcp_support

Install support for DHCP. Default: false

krb5_support

Install support for Kerberos. Default: false

wpa_supplicant

Install wpa_supplicant utility. Default: false

winbind_support

Add the radius user to the winbind privileged group. You must install winbind separately. Default: false.

log_destination

Configure destination of log messages. Valid values are files, syslog, stdout and stderr. Default: files.

syslog

Add a syslog rule (using the saz/rsyslog module). Default: false.

log_auth

Log authentication requests (yes/no). Default: no.

package_ensure

Choose whether the package is just installed and left (installed), or updated every Puppet run (latest). Default: installed

class { 'freeradius':
  max_requests    => 4096,
  max_servers     => 4096,
  mysql_support   => true,
  perl_support    => true,
  utils_support   => true,
  wpa_supplicant  => true,
  winbind_support => true,
  syslog          => true,
  log_auth        => 'yes',
}

freeradius::status_server

The freeradius::status_server class enabled the status server. To remove the status server, do not include this class and the server will be removed.

secret

The shared secret for the status server. Required.

port

The port to listen for status requests on. Default: 18121

listen

The address to listen on. Defaults to listen on all addresses but you could set this to $::ipaddress or 127.0.0.1. Default: *

  # Enable status server
  class { 'freeradius::status_server':
    port   => '18120',
    secret => 't0pSecret!',
  }

freeradius::control_socket

The freeradius::control_socket class enables the control socket which can be used with RADMIN. To remove the control socket, do not include this class and the socket will be removed.

mode

Whether the control socket should be read-only or read-write. Choose from ro, rw. Default: ro.

  # Enable control socket
  class { 'freeradius::control_socket':
    mode => 'ro',
  }

Resources

freeradius::attr

Install arbitrary attribute filters from a flat file. These are installed in an appropriate module config directory. The contents of the attr_filter module are automatically updated to reference the filters.

key

Specify a RADIUS attribute to be the key for this attribute filter. Enter only the string part of the name.

prefix

Specify the prefix for the attribute filter name before the dot, e.g. filter.post_proxy. This is usually set to filter on FR2 and attr_filter on FR3. Default: filter.

freeradius::attr { 'eduroamlocal':
  key    => 'User-Name',
  prefix => 'attr_filter',
  source => 'puppet:///modules/site_freeradius/eduroamlocal',
}

freeradius::blank

Selectively blank certain stock config files that aren't required. This is preferable to deleting them because the package manager will replace certain files next time the package is upgraded, potentially causing unexpected behaviour.

The resource title should be the relative path from the FreeRADIUS config directory to the file(s) you want to blank. You can pass multiple files in an array.

freeradius::blank { 'sites-enabled/default': }

freeradius::blank { [
  'sites-enabled/default',
  'eap.conf',
]: }

freeradius::cert

Install certificates as provided. These are installed in certs. Beware that any certificates not deployed by Puppet will be purged from this directory.

freeradius::cert { 'mycert.pem':
  source => 'puppet:///modules/site_freeradius/mycert.pem',
  type   => 'key',
}

freeradius::cert { 'mycert.pem':
  content => '<your key/cert content here>',
  type    => 'key',
}

type

Set file permissions on the installed certificate differently depending on whether this is a private key or a public certificate. Note that the default is to treat the file as a private key and remove world-readable privileges. Allowable values: cert, key. Default: key.

freeradius::client

Define RADIUS clients as seen in clients.conf

# Single host example
freeradius::client { "wlan-controller01":
  ip        => '192.168.0.1',
  secret    => 'testing123',
  shortname => 'wlc01',
  nastype   => 'other',
  port      => '1645-1646',
  firewall  => true,
}

# Range example
freeradius::client { "wlan-controllers":
  ip        => '192.168.0.0/24',
  secret    => 'testing123',
  shortname => 'wlc01',
  nastype   => 'other',
  port      => '1645-1646',
  firewall  => true,
}

# Huntgroup Example
freeradius::client { "asa01":
  ip         => '192.168.0.1',
  secret     => 'testing123',
  huntgroups => [
    { name       => 'firewall',
      conditions => [ 'NAS-IP-Address == 192.168.0.1' ] },
  ]
}

ip

The IP address of the client or range in CIDR format. For IPv6, use ipv6addr. ip and ip6 are mutually exclusive but one must be supplied. Default: undef.

ip6

The IPv6 address of the client or range in CIDR format. ip and ip6 are mutually exclusive but one must be supplied. Default: undef.

shortname

A short alias that is used in place of the IP address or fully qualified hostname provided in the first line of the section. Defaults to resource name.

secret

The RADIUS shared secret used for communication between the client/NAS and the RADIUS server. Required.

virtual_server

The virtual server that traffic from this client should be sent to. Default: undef.

nastype

The nastype attribute is used to tell the checkrad.pl script which NAS-specific method it should use when checking simultaneous use. See man clients.conf for a list of all options. Default: undef.

proto

Transport protocol used by the client. If unspecified, defaults to "udp", which is the traditional RADIUS transport. Valid values are udp, tcp or * for both of them. Default: undef.

require_message_authenticator

Old-style clients do not send a Message-Authenticator in an Access-Request. RFC 5080 suggests that all clients SHOULD include it in an Access-Request. Valid values are yes and no. Default: no.

login

Login used by checkrad.pl when querying the NAS for simultaneous use. Default: undef.

password

Password used by checkrad.pl when querying the NAS for simultaneous use. Default: undef.

coa_server

A pointer to the home_server_pool OR a home_server section that contains the CoA configuration for this client. Default: undef.

response_window