From 1df68aa24de34eaca7784963b2a0596ee577f2fe Mon Sep 17 00:00:00 2001 From: Matthew Newton Date: Fri, 11 Sep 2015 23:07:27 +0100 Subject: [PATCH] small documentation fix/cleanups --- doc/README | 93 ++++++++++++++++++++++++++++-------------------------- doc/bugs | 53 ++++++++++++++++++------------- 2 files changed, 80 insertions(+), 66 deletions(-) diff --git a/doc/README b/doc/README index 097a4e3870..439aedc6d1 100644 --- a/doc/README +++ b/doc/README @@ -2,7 +2,7 @@ All code in this server was written for this project. - The server is mostly compatible with livingston radiusd-2.01 + The server is mostly compatible with Livingston radiusd-2.01 (no menus or s/key support though) but with more features, such as: o Can limit the maximum number of simultaneous logins on a per-user basis! @@ -19,19 +19,13 @@ o Supports Vendor-Specific attributes o Supports many different plug-in modules for authentication, authorization, and accounting. - o No good documentation at all, just like the original radiusd 1.16! - Work on real manual pages is progressing slowly. For a large part you - can use the documentation of the Livingston 2.01 server. Just remember - that using Prefix and Suffix in both the "users" and the (FreeRadius - specific) "hints" file will give unpredictable results. Well actually - it will result in Prefix and Suffix probably not working in the "users" - file if you already stripped them off in the "hints" file. 2. INSTALLATION See the INSTALL file, in the parent directory. + 3. CONFIGURATION FILES For every file there is a fully commented example file included, that @@ -54,7 +48,7 @@ Every NAS (Network Access Server, also known as terminal server) should have an entry in this file with an abbreviated name and the type of NAS it - is. Currently FreeRadius supports the following NAS types: + is. Currently FreeRADIUS supports the following NAS types: Terminal Server Type in naslist @@ -116,8 +110,8 @@ You can uses spaces in usernames by escaping them with \ or by using quotes. For example, "joe user" or joe\ user. - The FreeRadius server does not trim any spaces from a username received - from the portmaster (livingston does, in perl notation, $user =~ s/\s+.*//;) + The FreeRADIUS server does not trim any spaces from a username received + from the portmaster (Livingston does, in perl notation, $user =~ s/\s+.*//;) 3g. NEW RADIUS ATTRIBUTES (to be used in the USERS file). @@ -142,63 +136,73 @@ For example, "Wk2305-0855,Sa,Su2305-1655". - Radiusd calculates the number of seconds left in the time span, and + radiusd calculates the number of seconds left in the time span, and sets the Session-Timeout to that number of seconds. So if someones Login-Time is "Al0800-1800" and she logs in at 17:30, Session-Timeout is set to 1800 seconds so that she is kicked off at 18:00. + 4. LOG FILES -4a. /var/log/radutmp +4a. /var/log/radius/radutmp In this file the currently logged in users are held. The program "radwho" reads this file and gives you a summary. Rogue sessions can be deleted from this file with the "radzap" program. -4b. /var/log/radwtmp +4b. /var/log/radius/radwtmp This file is "wtmp" compatible and keeps a history of all radius logins/ logouts. This file can be read with the "last" program, and other Unix accounting programs (such as "ac" and "sac") can be used to produce a summary. -4c. /var/log/radius.log +4c. /var/log/radius/radius.log - All RADIUS informational. diagnostic and error messages are logged in - this file. If radiusd has been started with the "-y" flag, all logins - attempts will be logged in this file. For failed logins, the wrong password - will also be logged. With the "-z" flag, the passwords for successful - logins will be logged as well. That's pretty dangerous though in case - anyone unpriviliged ever manages to get access to this file! + All RADIUS informational, diagnostic and error messages are logged in + this file, including all login attempts. -4d. /var/log/radacct//detail +4d. /var/log/radius/radacct//detail - This is the original radius logfile, as written by all the livingston - radius servers. It's only created if the directory /var/log/radacct exists. - The name is the short name if one is defined in - /etc/raddb/naslist. + This is the original radius logfile, as written by all the Livingston + radius servers. It's only created if the directory + /var/log/radius/radacct exists. For more configuration options on the detail file please see - README.rlm_detail as it expands upon this greatly. + raddb/mods-available/detail as it expands upon this greatly. + 5. MORE INFO, SUPPORT - We know that the documentation provided is sparse. However it is not in - the scope of the radius server to provide a guide as to how terminal - servers works and how the RADIUS protocol works and is used. + The latest version of FreeRADIUS is always available from + the git repository hosted on GitHub at + + https://github.com/FreeRADIUS/freeradius-server + + or see + + http://freeradius.org/git/ + + for more information. + + There are two mailing lists for users and developers. General + user, administrator and configuration issues should be discussed + on the users list at: + + http://lists.freeradius.org/mailman/listinfo/freeradius-users + + When asking for help on the users list, be sure the include a + detailed and clear description of the problem, together with + full debug output from FreeRADIUS, obtained by running - The latest version of FreeRadius is always available through - anonymous CVS from cvs.freeradius.org - for more info, see - + radiusd -X - There are two GNU Mailman mailing lists hosted by Cistron Internet Services: - a 'users' list, at: + Developers only discussion is to be had on the devel list: - http://lists.freeradius.org/pipermail/freeradius-users/ + http://lists.freeradius.org/mailman/listinfo/freeradius-devel - and a 'developers only' list, at + Please do not raise general configuration issues here. - http://lists.freeradius.org/pipermail/freeradius-devel/ 6. OTHER INFORMATION @@ -234,14 +238,15 @@ todo/ TODO list and assorted files. - If you have ANY problems, concerns, or surprises when running the -server, then run it in debugging mode, as root, from the command line: + If you have ANY problems, concerns, or surprises when running + the server, then run it in debugging mode, as root, from the + command line: -$ radiusd -X + $ radiusd -X -It will produce a large number of messages. The answers to many -questions, and the solution to many problems, can usually be found in -these messages. + It will produce a large number of messages. The answers to many + questions, and the solution to many problems, can usually be found in + these messages. For further details, see: diff --git a/doc/bugs b/doc/bugs index 0644132958..6a7843fb4f 100644 --- a/doc/bugs +++ b/doc/bugs @@ -1,6 +1,6 @@ BUGS -0.INTRODUCTION +0. INTRODUCTION The FreeRADIUS web site is at , and most information referenced in this document can be found there. @@ -10,7 +10,8 @@ BUGS development list to discuss it. If you're the type who know little about how to code, then this is the place for you! -1.YOU FOUND A BUG + +1. YOU FOUND A BUG Where the server terminates ungracefully due to a bus error, segmentation violation, or other memory error, you should create @@ -31,9 +32,10 @@ BUGS Please make sure to READ and RESPECT the house-rules. You will get much better response and much faster if you do! -2.CORE DUMPS - If the server, or one of the accompyaning programs core dumps, then +2. CORE DUMPS + + If the server, or one of the accompanying programs core dumps, then you should rebuild the server as follows: $ ./configure --enable-developer @@ -56,6 +58,11 @@ BUGS and follow the instructions in section 4, below. + You can also enable the "panic_action" given in raddb/radiusd.conf. + See the comments in that file for more details about automatically + collecting gdb debugging information when the server crashes. + + 3. DEBUGGING A LIVE SERVER If you can't get a core dump, or the problem doesn't result in a @@ -77,7 +84,7 @@ BUGS (gdb) set args ... Where the "..." are the command-line arguments you normally pass to - radiusd. Fo debugging, you probably want to do: + radiusd. For debugging, you probably want to do: (gdb) set args -f @@ -92,6 +99,7 @@ BUGS And follow the instructions in section 4, below. + 4. OBTAINING USEFUL INFORMATION Once you have a core dump loaded into gdb, or FreeRADIUS running under @@ -125,6 +133,7 @@ BUGS You should provide the issue number in any mail sent to the user's list. + 5. VALGRIND On Linux systems, "valgrind" is a useful tool that can catch certain @@ -138,27 +147,27 @@ $ valgrind --tool=memcheck --leak-check=full radiusd -Xm inside of the FreeRADIUS source should be brought to our attention. -6. Running with "screen" +6. RUNNING WITH "SCREEN" If the bug is a crash of the server, and it takes a long time for the crash to happen, perform the following steps: - * log in as root - * open a screen session (http://blogamundo.net/code/screen/) - $ screen bash - * make sure FreeRADIUS is not running - * make sure you have all the debug symbols about, or a debugable - version of the server installed - * configure screen to log to a file; 'Ctrl-A H' - * type 'gdb /path/to/radius' (or /path/to/freeradius on Debian) - * at the (gdb) prompt, type 'run -X' - * detach from screen 'Ctrl-A D' - * when you notice FreeRADIUS has died, reconnect to your screen session - $ screen -D -r - * at the (gdb) prompt type 'where' or for *lots* of info try - 'thread apply all bt full' - * tell screen to stop logging, 'Ctrl-A H' - * logout from screen + * log in as root + * open a screen session (https://www.gnu.org/software/screen/) + $ screen bash + * make sure FreeRADIUS is not running + * make sure you have all the debug symbols about, or a debugable + version of the server installed + * configure screen to log to a file; 'Ctrl-A H' + * type 'gdb /path/to/radius' (or /path/to/freeradius on Debian) + * at the (gdb) prompt, type 'run -X' + * detach from screen 'Ctrl-A D' + * when you notice FreeRADIUS has died, reconnect to your screen session + $ screen -D -r + * at the (gdb) prompt type 'where' or for *lots* of info try + 'thread apply all bt full' + * tell screen to stop logging, 'Ctrl-A H' + * logout from screen -- -- 2.47.2