From: Alan T. DeKok Date: Sun, 17 Mar 2013 15:16:05 +0000 (-0400) Subject: Document conditional modules. X-Git-Tag: release_3_0_0_beta1~709 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d682c202f58f9a7c3f3999721d8ee22d64522d45;p=thirdparty%2Ffreeradius-server.git Document conditional modules. Update default configuration to allow for conditional modules. Update message about conditional modules to be clearer, and to point to the documentation. --- diff --git a/raddb/mods-available/README.rst b/raddb/mods-available/README.rst new file mode 100644 index 00000000000..8ffb7648fda --- /dev/null +++ b/raddb/mods-available/README.rst @@ -0,0 +1,79 @@ +Modules in Version 3 +==================== + +As of Version 3, all of the modules have been places in the +"mods-available/" directory. This practice follows that used by other +servers such as Nginx, Apache, etc. The "modules" directory should +not be used. + +Modules are enabled by creating a file in the mods-enabled/ directory. +You can also create a soft-link from one directory to another:: + + $ cd raddb/mods-enabled + $ ln -s ../mods-available/foo + +This will enable module "foo". Be sure that you have configured the +module correctly before enabling it, otherwise the server will not +start. You can verify the server configuration by running +"radiusd -XC". + +A large number of modules are enabled by default. This allows the +server to work with the largest number of authentication protocols. +Please be careful when disabling modules. You will likely need to +edit the "sites-enabled/" files to remove references to any disabled +modules. + +Conditional Modules +------------------- + +Version 3 allows modules to be conditionally loaded. This is useful +when you want to have a virtual server which references a module, but +does not require it. Instead of editing the virtual server file, you +can just conditionally enable the module. + +Modules are conditionally enabled by adding a "-" before their name in +a virtual server. For example, you can do:: + + server { + authorize { + ... + ldap + -sql + ... + } + } + +This says "require the LDAP module, but use the SQL module only if it +is configured." + +This feature is not very useful for production configurations. It is, +however, very useful for the default examples that ship with the +server. + +Ignoring module +--------------- + +If you see this message:: + + Ignoring module (see raddb/mods-available/README.rst) + +Then you are in the right place. Most of the time this message can be +ignored. The message can be fixed by find the references to "-module" +in the virtual server, and deleting them. + +Another way to fix it is to configure the module, as described above. + +Simplification +-------------- + +Allowing conditional modules simplifies the default virtual servers +that are shipped with FreeRADIUS. This means that if you want to +enable LDAP (for example), you no longer need to edit the files in +raddb/sites-available/ in order to enable it. + +Instead, you should edit the raddb/mods-available/ldap file to point +to your local LDAP server. Then, enable the module via the soft-link +method described above. + +Once the module is enabled, it will automatically be used in the +default configuration. diff --git a/raddb/sites-available/default b/raddb/sites-available/default index 0aa00547d95..fde87b52438 100644 --- a/raddb/sites-available/default +++ b/raddb/sites-available/default @@ -327,7 +327,7 @@ authorize { # is meant to mirror the "users" file. # # See "Authorization Queries" in sql.conf -# sql + -sql # # If you are using /etc/smbpasswd, and are also doing @@ -336,9 +336,8 @@ authorize { # etc_smbpasswd # - # The ldap module will set Auth-Type to LDAP if it has not - # already been set -# ldap + # The ldap module reads passwords from the LDAP database. + -ldap # # Enforce daily limits on time spent logged in. @@ -449,11 +448,17 @@ authenticate { # unix - # Uncomment it if you want to use ldap for authentication + # Uncomment it if you want to use ldap for authentication + # + # Note that this means "check plain-text password against + # the ldap database", which means that EAP won't work, + # as it does not supply a plain-text password. + # + # We do NOT recommend using this. LDAP servers are databases. + # They are NOT authentication servers. FreeRADIUS is an + # authentication server, and knows what to do with authentication. + # LDAP servers do not. # - # Note that this means "check plain-text password against - # the ldap database", which means that EAP won't work, - # as it does not supply a plain-text password. # Auth-Type LDAP { # ldap # } @@ -562,7 +567,7 @@ accounting { # Log traffic to an SQL database. # # See "Accounting queries" in sql.conf -# sql + -sql # # If you receive stop packets with zero session length, @@ -623,15 +628,15 @@ post-auth { # # If you want to have a log of authentication replies, - # un-comment the following line, and the 'detail reply_log' - # section, above. + # un-comment the following line, and enable the + # 'detail reply_log' module. # reply_log # # After authenticating the user, do another SQL query. # # See "Authentication Logging Queries" in sql.conf -# sql + -sql # # Instead of sending the query to the SQL server, @@ -737,7 +742,7 @@ post-auth { # Post-Auth-Type REJECT { # log failed authentications in SQL, too. -# sql + -sql attr_filter.access_reject # Insert EAP-Failure message if the request was diff --git a/raddb/sites-available/inner-tunnel b/raddb/sites-available/inner-tunnel index cd5a0a7c292..ce53e4f7949 100644 --- a/raddb/sites-available/inner-tunnel +++ b/raddb/sites-available/inner-tunnel @@ -129,7 +129,7 @@ authorize { # is meant to mirror the "users" file. # # See "Authorization Queries" in sql.conf -# sql + -sql # # If you are using /etc/smbpasswd, and are also doing @@ -138,9 +138,8 @@ authorize { # etc_smbpasswd # - # The ldap module will set Auth-Type to LDAP if it has not - # already been set -# ldap + # The ldap module reads passwords from the LDAP database. + -ldap # # Enforce daily limits on time spent logged in. @@ -228,6 +227,12 @@ authenticate { # Note that this means "check plain-text password against # the ldap database", which means that EAP won't work, # as it does not supply a plain-text password. + # + # We do NOT recommend using this. LDAP servers are databases. + # They are NOT authentication servers. FreeRADIUS is an + # authentication server, and knows what to do with authentication. + # LDAP servers do not. + # # Auth-Type LDAP { # ldap # } @@ -261,21 +266,17 @@ session { # Once we KNOW that the user has been authenticated, there are # additional steps we can take. post-auth { - # Note that we do NOT assign IP addresses here. - # If you try to assign IP addresses for EAP authentication types, - # it WILL NOT WORK. You MUST use DHCP. - # # If you want to have a log of authentication replies, - # un-comment the following line, and the 'detail reply_log' - # section, above. + # un-comment the following line, and enable the + # 'detail reply_log' module. # reply_log # # After authenticating the user, do another SQL query. # # See "Authentication Logging Queries" in sql.conf -# sql + -sql # # Instead of sending the query to the SQL server, @@ -299,7 +300,7 @@ post-auth { # Post-Auth-Type REJECT { # log failed authentications in SQL, too. -# sql + -sql attr_filter.access_reject } diff --git a/src/main/modules.c b/src/main/modules.c index 4661bd98d7c..aaab0fa9d66 100644 --- a/src/main/modules.c +++ b/src/main/modules.c @@ -854,7 +854,7 @@ static int load_component_section(CONF_SECTION *cs, * It's OK for the module to not exist. */ if (!this && modname && (modname[0] == '-')) { - DEBUGW("Not loading module \"%s\" as it is not enabled", modname + 1); + DEBUGW("Ignoring \"%s\" (see raddb/mods-available/README.rst)", modname + 1); continue; }