Merge pull request #20 from djjudas21/freeradius3

Support for FreeRADIUS 3

README.md

@@ -16,9 +16,13 @@
        * [`freeradius::client`](#freeradiusclient)
        * [`freeradius::config`](#freeradiusconfig)
        * [`freeradius::dictionary`](#freeradiusdictionary)
+       * [`freeradius::home_server`](#freeradiushomeserver)
+       * [`freeradius::home_server_pool`](#freeradiushomeserverpool)
        * [`freeradius::instantiate`](#freeradiusinstantiate)
+       * [`freeradius::ldap`](#freeradiusldap)
        * [`freeradius::module`](#freeradiusmodule)
        * [`freeradius::policy`](#freeradiuspolicy)
+       * [`freeradius::realm`](#freeradiusrealm)
        * [`freeradius::site`](#freeradiussite)
        * [`freeradius::sql`](#freeradiussql)
        * [`freeradius::statusclient`](#freeradiusstatusclient)
@@ -29,9 +33,8 @@
 ## Overview
 
 This module installs and configures [FreeRADIUS](http://freeradius.org/) server
-on Linux. This module was written for use with FreeRADIUS 2.x and has not been
-tested with FreeRADIUS 3.x. It was designed with CentOS in mind but should
-work on other distributions.
+on Linux. It supports FreeRADIUS 2.x and 3.x. It was designed with CentOS in mind
+but should work on other distributions.
 
 ## Module Description
 
@@ -143,10 +146,22 @@ Whether the control socket should be read-only or read-write. Choose from `ro`,
 
 #### `freeradius::attr`
 
-Install arbitrary attribute filters from a flat file. These are installed in `/etc/raddb/attr.d`
+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`.
 
 ```puppet
 freeradius::attr { 'eduroamlocal':
+  key    => 'User-Name',
+  prefix => 'attr_filter',
   source => 'puppet:///modules/site_freeradius/eduroamlocal',
 }
 ```
@@ -258,6 +273,84 @@ freeradius::dictionary { 'mydict':
   source => 'puppet:///modules/site_freeradius/dictionary.mydict',
 }
 ```
+#### `freeradius::home_server`
+
+This section defines a "Home Server" which is another RADIUS server that gets sent proxied requests.
+
+##### `secret`
+
+The shared secret use to "encrypt" and "sign" packets between FreeRADIUS and the home server.
+
+##### `type`
+
+Home servers can be sent Access-Request packets or Accounting-Request packets. Allowed values are:
+* `auth` Handles Access-Request packets
+* `acct`  Handles Accounting-Request packets
+* `auth+acct` Handles Access-Request packets at "port" and Accounting-Request packets at "port + 1"
+* `coa` Handles CoA-Request and Disconnect-Request packets.
+
+Default: `auth`
+
+##### `ipaddr`
+
+IPv4 address or hostname of the home server. Specify one of `ipaddr`, `ipv6addr` or `virtual_server`
+
+##### `ipv6addr`
+
+IPv6 address or hostname of the home server. Specify one of `ipaddr`, `ipv6addr` or `virtual_server`
+
+##### `virtual_server`
+
+If you specify a virtual_server here, then requests will be proxied internally to that virtual server.
+These requests CANNOT be proxied again, however. The intent is to have the local server handle packets
+when all home servers are dead. Specify one of `ipaddr`, `ipv6addr` or `virtual_server`
+
+##### `port`
+
+The port to which packets are sent. Usually 1812 for type "auth", and  1813 for type "acct".
+Older servers may use 1645 and 1646. Use 3799 for type "coa" Default: `1812`
+
+##### `proto`
+The transport protocol. If unspecified, defaults to "udp", which is the traditional
+RADIUS transport. It may also be "tcp", in which case TCP will be used to talk to
+this home server. Default: `udp`
+
+
+#### `freeradius::home_server_pool`
+
+##### `home_server`
+
+An array of one or more home servers. The names of the home servers are NOT the hostnames, but the names
+of the sections. (e.g. `home_server foo {...}` has name "foo".
+
+Note that ALL home servers listed here have to be of the same type. i.e. they all have to be "auth", or they all have to
+be "acct", or they all have to be "auth+acct".
+
+
+##### `type`
+
+The type of this pool controls how home servers are chosen.
+
+* `fail-over` the request is sent to the first live home server in the list.  i.e. If the first home server is marked "dead", the second one is chosen, etc.
+* `load-balance` the least busy home server is chosen For non-EAP auth methods, and for acct packets, we recommend using "load-balance". It will ensure the highest availability for your network. 
+* `client-balance` the home server is chosen by hashing the source IP address of the packet. This configuration is most useful to do simple load balancing for EAP sessions
+* `client-port-balance` the home server is chosen by hashing the source IP address and source port of the packet.
+* `keyed-balance` the home server is chosen by hashing (FNV) the contents of the Load-Balance-Key attribute from the control items.
+
+The default type is `fail-over`.
+
+##### `virtual_server`
+
+A `virtual_server` may be specified here.  If so, the "pre-proxy" and "post-proxy" sections are called when
+the request is proxied, and when a response is received.
+
+##### `fallback`
+
+If ALL home servers are dead, then this "fallback" home server is used. If set, it takes precedence over any realm-based
+fallback, such as the DEFAULT realm.
+
+For reasons of stability, this home server SHOULD be a virtual server. Otherwise, the fallback may itself be dead!
+
 
 #### `freeradius::instantiate`
 
@@ -267,6 +360,93 @@ Instantiate a module that is not automatically instantiated.
 freeradius::instantiate { 'mymodule': }
 ```
 
+#### `freeradius::ldap`
+
+Configure LDAP support for FreeRADIUS
+
+##### `identity`
+LDAP account for searching the directory. Required.
+
+##### `password`
+Password for the `identity` account. Required.
+
+##### `basedn`
+Unless overridden in another section, the dn from which all searches will start from. Required.
+
+##### `server`
+Hostname of IP address of the LDAP server. Note that this needs to match the name(s) in the LDAP server
+certificate, if you're using ldaps. Default: `localhost`
+
+##### `port`
+Port to connect to the LDAP server on. Default: `389`
+
+##### `uses`
+How many times the connection can be used before being re-established. This is useful for things
+like load balancers, which may exhibit sticky behaviour without it. `0` is unlimited. Default: `0`
+
+##### `idle`
+Sets the idle time before keepalive probes are sent. Default `60`
+
+This option may not be supported by your LDAP library. If this configuration entry appears in the
+output of `radiusd -X` then it is supported. Otherwise, it is unsupported and changing it will do nothing.
+
+##### `probes`
+Sets the maximum number of keepalive probes TCP should send before dropping the connection. Default: `3`
+
+This option may not be supported by your LDAP library. If this configuration entry appears in the
+output of `radiusd -X` then it is supported. Otherwise, it is unsupported and changing it will do nothing.
+
+##### `interval`
+Setss the interval in seconds between individual keepalive probes. Default: `3`
+
+This option may not be supported by your LDAP library. If this configuration entry appears in the
+output of `radiusd -X` then it is supported. Otherwise, it is unsupported and changing it will do nothing.
+
+##### `timeout`
+Number of seconds to wait for LDAP query to finish. Default: `10`
+
+##### `start`
+Connections to create during module instantiation. If the server cannot create specified number of
+connections during instantiation it will exit. Set to 0 to allow the server to start without the
+directory being available. This option only works with FR3; setting it on FR2 will have no effect.
+Default: `${thread[pool].start_servers}`
+
+##### `min`
+Minimum number of connections to keep open. This option only works with FR3; setting it on FR2 will have no effect.
+Default: `${thread[pool].min_spare_servers}`
+
+##### `max`
+Maximum number of connections. Default: `${thread[pool].max_servers}`
+
+##### `spare`
+Spare connections to be left idle. This option only works with FR3; setting it on FR2 will have no effect.
+Default: `${thread[pool].max_spare_servers}`
+
+##### `starttls`
+Set this to 'yes' to use TLS encrypted connections to the LDAP database by using the StartTLS extended operation.
+The StartTLS operation is supposed to be used with normal ldap connections instead of using ldaps (port 636) connections
+
+Default: `no`
+
+##### `cafile`
+Path to CA cert file for TLS
+
+##### `certfile`
+Path to cert file for TLS
+
+##### `keyfile`
+Path to key file for TLS
+
+##### `requirecert`
+Certificate Verification requirements. Choose from:
+'never' (do not even bother trying)
+'allow' (try, but don't fail if the certificate cannot be verified)
+'demand' (fail if the certificate does not verify)
+'hard'  (similar to 'demand' but fails if TLS cannot negotiate)
+
+Default: `allow`
+
+
 #### `freeradius::module`
 
 Install a module from a flat file.
@@ -293,6 +473,37 @@ freeradius::policy { 'my-policies':
 }
 ```
 
+#### `freeradius::realm`
+
+Define a realm in `proxy.conf`. Realms point to pools of home servers.
+
+##### `virtual_server`
+
+Set this to "proxy" requests internally to a virtual server. The pre-proxy and post-proxy sections are run just as with any
+other kind of home server.  The virtual server then receives the request, and replies, just as with any other packet.
+Once proxied internally like this, the request CANNOT be proxied internally or externally.
+
+##### `auth_pool`
+
+For authentication, the `auth_pool` configuration item should point to a `home_server_pool` that was previously
+defined.  All of the home servers in the `auth_pool` must be of type `auth`.
+
+##### `acct_pool`
+
+For accounting, the `acct_pool` configuration item should point to a `home_server_pool` that was previously
+defined.  All of the home servers in the `acct_pool` must be of type `acct`.
+
+##### `pool`
+
+If you have a `home_server_pool` where all of the home servers are of type `auth+acct`, you can just use the `pool`
+configuration item, instead of specifying both `auth_pool` and `acct_pool`.
+
+##### `nostrip`
+
+Normally, when an incoming User-Name is matched against the realm, the realm name is "stripped" off, and the "stripped"
+user name is used to perform matches.If you do not want this to happen, set this to `true`. Default: `false`.
+
+
 #### `freeradius::script`
 
 Install a helper script, e.g. which might be called upon by a virtual server. These are
@@ -482,13 +693,9 @@ required. A short alias that is used in place of the IP address or fully qualifi
 
 ## Limitations
 
-This module is targeted at FreeRADIUS 2.x running on CentOS 6. It has not been tested
-on other distributions, but might work. Likely sticking points with other distros are
-the names of packages, services and file paths.
-
-This module has not been tested on FreeRADIUS 3.x and almost certainly won't work
-without modification. FreeRADIUS 3.x support in this module will come onto the roadmap
-at the same time that my employer decides to start looking FreeRADIUS 3.x.
+This module is targeted at FreeRADIUS 2.x running on CentOS 6 and FreeRADIUS 3.x running
+on CentOS 7. It has not been thoroughly tested on other distributions, but might work.
+Likely sticking points with other distros are the names of packages, services and file paths.
 
 This module was written for use with Puppet 3.6 and 3.7, but should be quite agnostic
 to new versions of Puppet.
@@ -500,6 +707,9 @@ use probably haven't been written. Please send pull requests with new features a
 bug fixes. You are also welcome to file issues but I make no guarantees of
 development effort if the features aren't useful to my employer.
 
+When contributing code, please ensure your change works on FreeRADIUS 2.x and 3.x - at
+least until this module drops support for 2.x.
+
 ## Release Notes
 
 ### 0.4.5