From: Jorge Pereira Date: Thu, 15 Aug 2019 03:55:58 +0000 (-0300) Subject: doc: Rename README.adoc to index.adoc (#2892) X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4e7cf40566ccb1743f62db3efe3937de61a92aa8;p=thirdparty%2Ffreeradius-server.git doc: Rename README.adoc to index.adoc (#2892) * doc: Rename README.adoc to index.adoc * doc: Update references from README.adoc to index.adoc --- diff --git a/doc/ChangeLog b/doc/ChangeLog index a350d4b5e5b..9d1e14c513d 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,6 +1,6 @@ FreeRADIUS 4.0.0 Sun 10 Jul 2016 15:48:14 EDT urgency=medium Feature improvements - * For upgrade instructions, see doc/upgrade/README.adoc + * For upgrade instructions, see doc/upgrade/index.adoc * "authorize", "authenticate", "preacct", etc. are no longer used. * Dropped support for -i and -p flags in radiusd diff --git a/doc/all.mk b/doc/all.mk index a26fef0d9fa..fa1bb11ad5b 100644 --- a/doc/all.mk +++ b/doc/all.mk @@ -52,8 +52,7 @@ AUTO_ADOC_FILES := $(patsubst raddb/%,doc/raddb/%.adoc,$(CONF_FILES)) ADOC_FILES := $(BASE_ADOC_FILES) $(AUTO_ADOC_FILES) PDF_FILES := $(patsubst doc/%.adoc,doc/%.pdf,$(ADOC_FILES)) HTML_FILES := $(filter %html,$(patsubst doc/%.adoc,doc/%.html,$(ADOC_FILES)) \ - $(subst %home.adoc,index.html,$(ADOC_FILES)) \ - $(subst %README.adoc,index.html,$(ADOC_FILES))) + $(subst %home.adoc,index.html,$(ADOC_FILES))) # # Our "conf to Doxygen" stuff. @@ -178,25 +177,6 @@ doc/%.html: doc/%.adoc -b html5 -o $@ $< ${Q}perl -p -i -e 's,\.adoc,\.html,g; s,/.html",/",g; s/\.md\.html/\.html/g' $@ -html_build: $(HTML_FILES) - -# -# Create a soft-link between $path/{home || README}.html to $path/index.html -# -# We have to manually use a "for" loop because the source names are randomly -# "README" or "home". -# -HTML_INDEXES := $(filter %home.html,$(HTML_FILES)) -HTML_INDEXES += $(filter %README.html,$(HTML_FILES)) - -html_index: - ${Q}for x in $(HTML_INDEXES); do \ - if [ ! -L $$(dirname $$x)/index.html ] ; then \ - echo HTML-INDEX $$x; \ - (cd $$(dirname $$x) && ln -fs $$(basename $$x) index.html); \ - fi; \ - done - doc/%.pdf: doc/%.adoc @echo PDF $^ ${Q}$(ASCIIDOCTOR) $< -b docbook5 -o - | \ @@ -213,7 +193,7 @@ doc/%.pdf: doc/%.md .PHONY: asciidoc html pdf clean clean.doc asciidoc: $(ADOC_FILES) -html: html_build html_index +html: $(HTML_FILES) pdf: $(PDF_FILES) endif diff --git a/doc/howto/README.adoc b/doc/howto/index.adoc similarity index 100% rename from doc/howto/README.adoc rename to doc/howto/index.adoc diff --git a/doc/README.adoc b/doc/index.adoc similarity index 100% rename from doc/README.adoc rename to doc/index.adoc diff --git a/doc/raddb/README.adoc b/doc/raddb/README.adoc deleted file mode 100644 index e364bf903bc..00000000000 --- a/doc/raddb/README.adoc +++ /dev/null @@ -1,173 +0,0 @@ -= Welcome to Version 4.0 of FreeRADIUS - -WARNING: *PLEASE DO NOT USE VERSION 4. IT IS INTENDED ONLY FOR -DEVELOPERS. THE CONFIGURATION MAY CHANGE. THE BEHAVIOR MAY CHANGE. THE -DOCUMENTATION MAY CHANGE.* - -Version 4 is the result of years of effort by the FreeRADIUS developers. -The goal of v4 was to expand it’s feature set. Many features could not -be implemented because of limitations that have been in the server since -the beginning of the project. For example, in v3 and earlier releases, -we had the following limitations: - -* it was impossible to proxy one packet to multiple destinations -* it was impossible to catch a `failed` proxy, and fall back to local - authentication -* the server could not support multiple clients with different shared - secrets behind one NAT gateway -* the DHCP and VMPS was implemented by making them pretend to be RADIUS, - which limited their functionality -* the server did not support TACACS+ -* connections to databases were `synchronous`. If a database blocked, - it could eventually lock up the server - -All of these limitations and more have been removed. The downside of -these changes is that the some of the configuration has been changed. -Please see the <<../upgrade/#,upgrade>> file for instructions on -how to migrate a v3 configuration to v4. - -== Configuring the server - -When configuring the server, please start with the default -configuration. It is intended to work in the widest possible -circumstances, with minimal site-local changes. Most sites can just -configure a few modules such as `ldap` and `sql`, and the server -will do everything you need. More complex configurations require more -effort, of course. - -For more complex configurations, the best approach is to make a series -of small changes. Start the server after every change via -`radiusd -XC` to see if the configuration is OK. Use `radclient` to -send the server test packets. Read the debug output (`radiusd -X`) to -verify that the server is doing what you expect. - -For complex policies, it is best to write down what you want in plain -English. Be specific. Write down what the server receives in a packet, -which databases are used, and what the database should return. The more -detailed these explanations, the easier it will be to create a working -configuration. - -Take your time. It is better to make small incrementatal progress, than -to make massive changes, and then to spend weeks debugging it. - -== Organization - -The files in this directory are organized into logical groups, as -follows. - -* `mods-available/` - <>, with example configuration. -* `mods-enabled/` - Enabled modules that are being used by FreeRADIUS. -* `sites-available/` - <>, with example configuration. -* `sites-enabled/` - Enabled virtual servers that are being used by FreeRADIUS. -* `policy.d/` - example and live policies which implement standard rules and checks. -* `certs/` - Certificiates for EAP and for RADIUS over TLS. - -The directories are descrived in more detail below. - -=== `mods-available/` - -The `mods-available/` directory contains configuration for all of the -available modules. Each module configuration is different. Each file -contains documentation that describes what the module is, and how it -works. - -The directory contains almost 100 modules. Most configurations will only -use a few modules. The rest exist in order to serve as documentation and -worked examples. - -=== `mods-enabled/` - -The `mods-enabled/` directory contains the _enabled_ modules. The -files here should generally be soft links back to the -`mods-available/` directory. - -For example, the following commands would enable the `ldap` module: - -``` -cd mods-enabled/ -ln -s ../mods-available/ldap -``` - -Note that the `ldap` module must still be configured for the local systems. - -=== `mods-config/` - -This directory contains complex configuration files for modules loaded -from `mods-enabled/`. - -For example, the `sql` module can connect to multiple types of SQL -databases. Each SQL database has it’s own schema, along with default -queries for RADIUS, IP pools, DHCP, etc. If these files were placed into -the ’mods-available/` directory, that directory would get compled and -difficult to manage. - -Instead, the files are placed into a separate directory. - -Note that only a few modules require this extra configuration. - -=== `policy.d` - -The `policy.d/` directory contains sample policies that are used when -processing packets. These policies implement complex logic which often -uses multiple modules. - -There is no need to have `available` or `enabled` policies. All -policies are loaded by the server, and unused ones are ignored. - -=== `sites-available/` - -The `sites-available/` directory contains virtual servers which -process packets. They are similar to the virtual servers used by Apache -or Nginx. - -Each virtual server will begin with a `server` declaration, along with it’s name. e.g. `server default { ...`. The declaration is then followed by a `namespace =` -parameter, which describes which application protocol is being used in that virtual server. -e.g. `namespace = radius`. - -The virtual server will then contain zero or more `listen` subsections. Each `listen` subsection defines a network socket which is used to receive packets. - -The virtual server will then contain multiple `recv { ... }` and `send { ... }` -subsections. These subsections are used to process packets. - -Note that unlike v3, there are no longer any `authorize`, -`authenticate`, etc. sections. All of the `processing sections` have -been renamed. This change was necessary in order to simplify the -operation of the server, and to better support multiple protocols. - -Please see the <<../upgrade/#,upgrade>> file for more information -about these changes. - -The `sites-available/` directory contains many files. Each file is a -worked example of how to achieve a particular goal using FreeRADIUS. We -recommend reading these files in order to see how complex goals can be -achieved. - -=== `sites-enabled/` - -The `sites-enabled/` directory contains the _enabled_ virtual servers. -The files here should generally be soft links back to the `sites-available/` directory. - -For example, to enable the `default` virtual server, you can run these commands: - -``` -cd sites-enabled/ -ln -s ../sites-available/default -``` - -The standard installation of FreeRADIUS enables only a few virtual servers. - -=== `certs/` - -This directory contains certificates and configuration for EAP and RADIUS over TLS (i.e. RadSec). - -== List of config files - -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> diff --git a/doc/raddb/certs/README.adoc b/doc/raddb/certs/README.adoc deleted file mode 100644 index 8ad2a7fa842..00000000000 --- a/doc/raddb/certs/README.adoc +++ /dev/null @@ -1,233 +0,0 @@ -= Certificates - -This directory contains scripts to create the server certificates. To -make a set of default (i.e. test) certificates, simply type: - -``` -$ ./bootstrap -``` - -The `openssl` command will be run against the sample configuration -files included here, and will make a self-signed certificate authority -(i.e. root CA), and a server certificate. This "root CA" should be -installed on any client machine needing to do EAP-TLS, PEAP, or -EAP-TTLS. - -The Microsoft `XP Extensions` will be automatically included in the -server certificate. Without those extensions Windows clients will refuse -to authenticate to FreeRADIUS. - -The root CA and the `XP Extensions` file also contain a -crlDistributionPoints attribute. The latest release of Windows Phone -needs this to be present for the handset to validate the RADIUS server -certificate. The RADIUS server must have the URI defined but the CA need -not have…however it is best practice for a CA to have a revocation URI. -Note that whilst the Windows Mobile client cannot actually use the CRL -when doing 802.1X it is recommended that the URI be an actual working -URL and contain a revocation format file as there may be other OS -behaviour at play and future OSes that may do something with that URI. - -In general, you should use self-signed certificates for 802.1x (EAP) -authentication. When you list root CAs from other organisations in the -`ca_file`, you permit them to masquerade as you, to authenticate your -users, and to issue client certificates for `EAP-TLS`. - -If FreeRADIUS was configured to use `OpenSSL`, then simply starting the -server in root in debugging mode should also create test certificates, -i.e.: - -``` -$ radiusd -X -``` - -That will cause the `EAP-TLS` module to run the `bootstrap` script in -this directory. The script will be executed only once, the first time -the server has been installed on a particular machine. This bootstrap -script SHOULD be run on installation of any pre-built binary package for -your OS. In any case, the script will ensure that it is not run twice, -and that it does not over-write any existing certificates. - -If you already have CA and server certificates, rename (or delete) this -directory, and create a new `certs` directory containing your -certificates. Note that the `make install` command will NOT over-write -your existing `raddb/certs` directory, which means that the -`bootstrap` command will not be run. - -== New Installations - -We suggest that new installations use the test certificates for initial -tests, and then create real certificates to use for normal user -authentication. See the instructions below for how to create the various -certificates. The old test certificates can be deleted by running the -following command: - -``` -$ rm -f _.pem _.der _.csr _.crt _.key _.p12 serial* index.txt* -``` - -Then, follow the instructions below for creating real certificates. - -Once the final certificates have been created, you can delete the -`bootstrap` command from this directory, and delete the -`make_cert_command` configuration from the `tls` sub-section of -`raddb/mods-available/eap`. - -If you do not want to enable EAP-TLS, PEAP, or EAP-TTLS, then delete the -relevant sub-sections from the `raddb/mods-available/eap` file. - -== Root Certificate - -``` -$ vi ca.cnf -``` - -Edit the `input_password` and `output_password` fields to be the -password for the CA certificate. - -Edit the [certificate_authority] section to have the correct values for -your country, state, etc. - -``` -$ make ca.pem -``` - -This step creates the CA certificate. - -``` -$ make ca.der -``` - -This step creates the DER format of the self-signed certificate, which -is can be imported into Windows. - -== Server Certificate - -The following steps will let you create a server certificate for use -with TLS-based EAP methods, such as EAP-TLS, PEAP, and TTLS. Follow -similar steps to create an "inner-server.pem" file, for use with -EAP-TLS that is tunneled inside of another TLS-based EAP method. - -``` -$ vi server.cnf -``` - -Edit the `input_password` and `output_password` fields to be the -password for the server certificate. - -Edit the [server] section to have the correct values for your country, -state, etc. Be sure that the commonName field here is different from the -commonName for the CA certificate. - -``` -$ make server.pem -``` - -This step creates the server certificate. - -If you have an existing certificate authority, and wish to create a -certificate signing request for the server certificate, edit server.cnf -as above, and type the following command. - -``` -$ make server.csr -``` - -You will have to ensure that the certificate contains the XP extensions -needed by Microsoft clients. - -== Client Certificate - -Client certificates are used by EAP-TLS, and optionally by EAP-TTLS and -PEAP. The following steps outline how to create a client certificate -that is signed by the server certificate created above. You will have to -have the password for the server certificate in the "input_password" -and "output_password" fields of the server.cnf file. - -``` -$ vi client.cnf -``` - -Edit the `input_password` and `output_password` fields to be the -password for the client certificate. You will have to give these -passwords to the end user who will be using the certificates. - -Edit the [client] section to have the correct values for your country, -state, etc. Be sure that the commonName field here is the User-Name that -will be used for logins! - -``` -$ make client.pem -``` - -The users certificate will be in `emailAddress.pem`, i.e. `user@example.com.pem`. - -To create another client certificate, just repeat the steps for making a -client certificate, being sure to enter a different login name for `commonName`, -and a different password. - -== Performance - -EAP performance for EAP-TLS, TTLS, and PEAP is dominated by SSL -calculations. That is, a normal system can handle PAP authentication at -a rate of 10k packets/s. However, SSL involves RSA calculations, which -are very expensive. To benchmark your system, do: - -``` -$ openssl speed rsa -``` - -or - -``` -$ openssl speed rsa2048 -``` - -to test 2048 bit keys. - -That number is also the number of authentications/s that can be done for -`EAP-TLS` (or `TTLS`, or `PEAP`). - -== Compatibility - -The certificates created using this method are known to be compatible -with ALL operating systems. Some common issues are: - -* Windows requires certain OIDs in the certificates. If it doesn’t see - them, it will stop doing EAP. The most visible effect is that the client - starts EAP, gets a few `Access-Challenge` packets, and then a little while - later re-starts EAP. If this happens, see the FAQ, and the comments in - `raddb/mods-available/eap` for how to fix it. -* Windows requires the root certificates to be on the client PC. If it - doesn’t have them, you will see the same issue as above. -* Windows XP post SP2 has a bug where it has problems with certificate - chains. i.e. if the server certificate is an intermediate one, and not a - root one, then authentication will silently fail, as above. -* Some versions of Windows CE cannot handle 4K RSA certificates. They - will (again) silently fail, as above. -* In none of these cases will Windows give the end user any reasonable - error message describing what went wrong. This leads people to blame the - RADIUS server. That blame is misplaced. -* Certificate chains of more than 64K bytes are known to not work. This - is a problem in FreeRADIUS. However, most clients cannot handle 64K - certificate chains. Most Access Points will shut down the EAP session - after about 50 round trips, while 64K certificate chains will take about - 60 round trips. So don’t use large certificate chains. They will only - work after everyone upgrade everything in the network. -* All other operating systems are known to work with EAP and FreeRADIUS. - This includes Linux, *BSD, Mac OS X, Solaris, Symbian, along with all - known embedded systems, phones, WiFi devices, etc. -* Someone needs to ask Microsoft to please stop making life hard for - their customers. - -== Security Considerations - -The default certificate configuration files uses MD5 for message -digests, to maintain compatibility with network equipment that supports -only this algorithm. - -MD5 has known weaknesses and is discouraged in favour of SHA1 (see -http://www.kb.cert.org/vuls/id/836068 for details). If your network -equipment supports the SHA1 signature algorithm, we recommend that you -change the `ca.cnf`, `server.cnf`, and `client.cnf` files to -specify the use of SHA1 for the certificates. To do this, change the -`default_md` entry in those files from `md5` to `sha1`. diff --git a/doc/raddb/mods-available/README.adoc b/doc/raddb/mods-available/README.adoc deleted file mode 100644 index e1725171d87..00000000000 --- a/doc/raddb/mods-available/README.adoc +++ /dev/null @@ -1,152 +0,0 @@ -= Modules in Version 4 - -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 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 - -FreeRADIUS 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 { - recv Access-Request { - ... - 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 mods-available/README.adoc) -``` - -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 -`sites-available/` in order to enable it. - -Instead, you should edit the `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. - -== List of available modules - -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> diff --git a/doc/raddb/mods-config/README.adoc b/doc/raddb/mods-config/README.adoc deleted file mode 100644 index c812b85360b..00000000000 --- a/doc/raddb/mods-config/README.adoc +++ /dev/null @@ -1,21 +0,0 @@ -= The mods-config Directory - -This directory contains module-specific configuration files. These files -are in a format different from the one used by the main `radiusd.conf` -files. Earlier versions of the server had many module-specific files in -the main `raddb` directory. The directory contained many files, and it -was not clear which files did what. - -For Version 3 of FreeRADIUS, we have moved to a consistent naming -scheme. Each module-specific configuration file is placed in this -directory, in a subdirectory named for the module. Where necessary, -files in the subdirectory have been named for the processing section -where they are used. - -For example, the `users` file is now located in -`mods-config/files/authorize`. That filename tells us three things: - -* The file is used in the `authorize` section. -* The file is used by the `files` module. -* It is a `module configuration` file, which is a specific format. - diff --git a/doc/raddb/sites-available/README.adoc b/doc/raddb/sites-available/README.adoc deleted file mode 100644 index 17a1106194a..00000000000 --- a/doc/raddb/sites-available/README.adoc +++ /dev/null @@ -1,374 +0,0 @@ -== Virtual Servers - -FreeRADIUS 4.0 supports virtual servers. This is probably the single -largest change that is NOT backwards compatible with 1.x. - -The virtual servers do NOT have to be set up with the `sites-available` -and `sites-enabled` directories. You can still have one "radiusd.conf" -file, and put the server configuration there: - -``` -... -server { - recv Access-Request { - ... - } - authenticate pap { - ... - } - ... -} -... -``` - -The power of virtual servers lies in their ability to separate policies. -A policy can be placed into a virtual server, where it is guaranteed to -affect only the requests that are passed through that virtual server. In -1.x, the policies were global, and it sometimes took much effort to -write a policy so that it only applied in certain limited situations. - -=== What do we mean by "virtual server"? - -A virtual server is a (nearly complete) RADIUS server, just like a -configuration for FreeRADIUS 1.x. However, FreeRADIUS can now run -multiple virtual servers at the same time. The virtual servers can even -proxy requests to each other! - -The simplest way to create a virtual server is to take the all of the -request processing sections from radius.conf, ("authorize" , -"authenticate", etc.) and wrap them in a "server \{}" block, as -above. - -You can create another virtual server by: - -* defining a new "server foo \{…}" section in `radiusd.conf` -* Putting the normal "authorize", etc. sections inside of it -* Adding a "listen" section _inside_ of the "server" section. - -e.g. - -``` -... -server foo { - listen { - ipaddr = 127.0.0.1 - port = 2000 - type = auth - } - - recv Access-Request { - update control { - Cleartext-Password := "bob" - } - pap - } - - authenticate pap { - pap - } -} -... -``` - -With that text added to `radiusd.conf`, run the server in debugging mode -(`radiusd -X`), and in another terminal window, type: - -``` -$ radtest bob bob localhost:2000 0 testing123 -``` - -You should see the server return an Access-Accept. - -=== Capabilities and limitations - -The only sub-sections that can appear in a virtual server section are: - -``` -listen -client -authorize -authenticate -post-auth -pre-proxy -post-proxy -preacct -accounting -session -``` - -All other configuration parameters (modules, etc.) are global. - -Inside of a virtual server, the authorize, etc. sections have their -normal meaning, and can contain anything that an authorize section could -contain in 1.x. - -When a "listen" section is inside of a virtual server definition, it -means that all requests sent to that IP/port will be processed through -the virtual server. There cannot be two "listen" sections with the -same IP address and port number. - -When a "client" section is inside of a virtual server definition, it -means that that client is known only to the "listen" sections that are -also inside of that virtual server. Not only is this client definition -available only to this virtual server, but the details of the client -configuration is also available only to this virtual server. - -i.e. Two virtual servers can listen on different IP address and ports, -but both can have a client with IP address 127.0.0.1. The shared secret -for that client can be different for each virtual server. - -=== More complex "listen" capabilities - -The "listen" sections have a few additional configuration items that -were not in 1.x, and were not mentioned above. These configuration items -enable almost any mapping of IP / port to clients to virtual servers. - -The configuration items are: - -``` -virtual_server = - - If set, all requests sent to this IP / port are processed - through the named virtual server. - - This directive can be used only for "listen" sections - that are global. i.e. It CANNOT be used if the - "listen" section is inside of a virtual server. - -clients = - - If set, the "listen" section looks for a "clients" section: - - clients { - ... - } - - It looks inside of that named "clients" section for - "client" subsections, at least one of which must - exist. Each client in that section is added to the - list of known clients for this IP / port. No other - clients are known. - - If it is set, it over-rides the list of clients (if - any) in the same virtual server. Note that the - clients are NOT additive! - - If it is not set, then the clients from the current - virtual server (if any) are used. If there are no - clients in this virtual server, then the global - clients are used. - - i.e. The most specific directive is used: - * configuration in this "listen" section - * clients in the same virtual server - * global clients - - The directives are also *exclusive*, not *additive*. - If you have one client in a virtual server, and - another client referenced from a "listen" section, - then that "listen" section will ONLY use the second - client. It will NOT use both clients. -``` - -=== More complex "client" capabilities - -The "client" sections have a few additional configuration items that -were not in 1.x, and were not mentioned above. These configuration items -enable almost any mapping of IP / port to clients to virtual servers. - -The configuration items are: - -``` -virtual_server = - - If set, all requests from this client are processed - through the named virtual server. - - This directive can be used only for "client" sections - that are global. i.e. It CANNOT be used if the - "client" section is inside of a virtual server. -``` - -If the "listen" section has a "server" entry, and a matching client -is found ALSO with a "server" entry, then the clients server is used -for that request. - -=== Worked examples - -Listening on one socket, and mapping requests from two clients to two -different servers. - -``` -listen { - ... -} -client one { - ... - virtual_server = server_one -} -client two { - ... - virtual_server = server_two -} -server server_one { - recv Access-Request { - ... - } - ... -} -server server_two { - recv Access-Request { - ... - } - ... -} -``` - -This could also be done as: - -``` -listen { - ... - virtual_server = server_one -} -client one { - ... -} -client two { - ... - virtual_server = server_two -} -server server_one { - recv Access-Request { - ... - } - ... -} -server server_two { - recv Access-Request { - ... - } - ... -} -``` - -In this case, the default server for the socket is "server_one", so -there is no need to set that in the client "one" configuration. The -"server_two" configuration for client "two" over-rides the default -setting for the socket. - -Note that the following configuration will NOT work: - -``` -listen { - ... - virtual_server = server_one -} -client one { - ... -} -server server_one { - recv Access-Request { - ... - } - ... -} -server server_two { - client two { - ... - } - recv Access-Request { - ... - } - ... -} -``` - -In this example, client "two" is hidden inside of the virtual server, -where the "listen" section cannot find it. - -=== Outlined examples - -This section outlines a number of examples, with alternatives. - -* one server, multiple sockets -** multiple "listen" sections in a "server" section -* one server per client -** define multiple servers -** have a global "listen" section -** have multiple global "clients", each with "virtual_server = X" -* two servers, each with their own sockets -** define multiple servers -** put "client" sections into each "server" -** put a "listen" section into each "server" -+ -Each server can list the same client IP, and the secret can be -different. -* two sockets, sharing a list of clients, but pointing to different -servers -** define global "listen" sections -** in each, set "virtual_server = X" -** in each, set "clients = Y" -** define "clients Y" section, containing multiple clients. -+ -This also means that you can have a third socket, which doesn’t share -any of these clients. - -=== How to decide what to do - -If you want _completely_ separate policies for a socket or a client, -then create a separate virtual server. Then, map the request to that -server by setting configuration entries in a "listen" section or in a -"client" section. - -Start off with the common cases first. If most of the clients and/or -sockets get a particular policy, make that policy the default. Configure -it without paying attention to the sockets or clients you want to add -later, and without adding a second virtual server. Once it works, then -add the second virtual server. - -If you want to re-use the previously defined sockets with the second -virtual server, then you will need one or more global "client" -sections. Those clients will contain a "virtual_server = …" entry that -will direct requests from those clients to the appropriate virtual -server. - -=== List of provided virtual servers - -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> diff --git a/doc/schemas/logstash/README.adoc b/doc/schemas/logstash/index.adoc similarity index 100% rename from doc/schemas/logstash/README.adoc rename to doc/schemas/logstash/index.adoc diff --git a/doc/source/README.adoc b/doc/source/index.adoc similarity index 100% rename from doc/source/README.adoc rename to doc/source/index.adoc diff --git a/doc/upgrade/README.adoc b/doc/upgrade/index.adoc similarity index 100% rename from doc/upgrade/README.adoc rename to doc/upgrade/index.adoc diff --git a/raddb/certs/README.md b/raddb/certs/README.md index c6a5e2550c0..dcd429446e6 100644 --- a/raddb/certs/README.md +++ b/raddb/certs/README.md @@ -1,3 +1,3 @@ # Certificates -Please see the `doc/raddb/certs/README.adoc` for full documentation. +Please see the `doc/raddb/certs/index.adoc` for full documentation. diff --git a/raddb/mods-available/eap b/raddb/mods-available/eap index 6103590e104..bb25caf9cd0 100644 --- a/raddb/mods-available/eap +++ b/raddb/mods-available/eap @@ -142,7 +142,7 @@ eap { # # ## Common TLS configuration for TLS-based EAP types # - # See `doc/raddb/certs/README.adoc` for additional comments on certificates. + # See `doc/raddb/certs/index.adoc` for additional comments on certificates. # # If OpenSSL was not found at the time the server was built, the `tls`, # `ttls`, and `peap` sections will be ignored. diff --git a/raddb/radiusd.conf.in b/raddb/radiusd.conf.in index 86c538724fe..43d6dbee2df 100644 --- a/raddb/radiusd.conf.in +++ b/raddb/radiusd.conf.in @@ -699,6 +699,6 @@ policy { # # For more documentation on virtual servers, see: # -# `doc/raddb/sites-available/README.adoc` +# `doc/raddb/sites-available/index.adoc` # $INCLUDE sites-enabled/ diff --git a/scripts/asciidoc/conf2adoc b/scripts/asciidoc/conf2adoc index b66093c3949..5e7d9963bfc 100755 --- a/scripts/asciidoc/conf2adoc +++ b/scripts/asciidoc/conf2adoc @@ -35,8 +35,8 @@ while () { } close FILE; -$links{"sites-available/"} = "$opt_a/sites-available/README.adoc"; -$links{"mods-available/"} = "$opt_a/mods-available/README.adoc"; +$links{"sites-available/"} = "$opt_a/sites-available/index.adoc"; +$links{"mods-available/"} = "$opt_a/mods-available/index.adoc"; sub process_file { my $input = shift; diff --git a/src/lib/unlang/compile.c b/src/lib/unlang/compile.c index 9318cf50a4b..94528641672 100644 --- a/src/lib/unlang/compile.c +++ b/src/lib/unlang/compile.c @@ -2125,7 +2125,7 @@ static unlang_t *compile_children(unlang_group_t *g, unlang_t *parent, unlang_co name = cf_pair_attr(cp); if (name[0] == '-') { cf_log_warn(cp, "Ignoring \"%s\" " - "(see doc/raddb/mods-available/README.adoc)", name + 1); + "(see doc/raddb/mods-available/index.adoc)", name + 1); continue; }