From 55db31a28ce30e2ad7e860a8976926fb2f521df9 Mon Sep 17 00:00:00 2001 From: aland Date: Mon, 30 Sep 2002 18:43:47 +0000 Subject: [PATCH] Re-arranged the documentation, to make it easier to follow for people who've never done this before. --- INSTALL | 86 +++++++++++++++++++++++++++++++++++++++++-- README | 61 +++++++++++++++++++++---------- doc/README | 121 +++++++++++++++++++++++++++---------------------------------- 3 files changed, 178 insertions(+), 90 deletions(-) diff --git a/INSTALL b/INSTALL index 6f37443..a7322ae 100644 --- a/INSTALL +++ b/INSTALL @@ -1,5 +1,9 @@ - Please read the README in the doc/ subdirectory. Section 2 gives you -complete details on how to configure, compile and install FreeRADIUS. +1. INSTALLATION + + Ignore this file if you have a pre-installed binary package. + + +1a. SIMPLE INSTALLATION If you do not need to modify the default configuration, then take the following steps to build and install the server: @@ -9,7 +13,83 @@ the following steps to build and install the server: $ make $ make install - Then, start the server in debugging mode: + +1b. CUSTOM INSTALLATION + + FreeRADIUS has autoconf support. This means you have to run +./configure, and then run make. To see which configuration options +are supported, run './configure --help', and read it's output. The +following list is a selection from the available flags: + + --enable-shared[=PKGS] build shared libraries [default=yes] + --enable-static[=PKGS] build static libraries [default=yes] + --enable-fast-install[=PKGS] optimize for fast installation [default=yes] + --with-logdir=DIR Directory for logfiles [LOCALSTATEDIR/log] + --with-radacctdir=PATH Directory for detail files [LOGDIR/radacct] + --with-raddbdir=DIR Directory for config files [SYSCONFDIR/raddb] + --with-threads Use threads, if available. (default=yes) + --with-snmp Compile in SNMP support. (default=yes) + --disable-ltdl-install Do not install libltdl + --with-experimental-modules Use experimental and unstable modules. (default=no) + --enable-developer Turns on super-duper-extra-compile-warnings + when using gcc. + + To get the defaults that Cistron Radius used up to 1.5.4.3-beta18, use: + + ./configure --localstatedir=/var --sysconfdir=/etc + + That means binaries will get installed in /usr/local/{bin,sbin}, +manpages in /usr/local/man, configuration files in /etc/raddb, and +logfiles in /var/log and /var/log/radacct. + + Now type "make". The binaries will be compiled. + + Then do "make install". That will install the binaries, the 'man' +pages, and MAY install the configuration files. If you have not +installed a RADIUS server before, then the configuration files for +FreeRADIUS will be installed. If you already have a RADIUS server +installed, then FreeRADIUS WILL NOT over-write your current +configuration. It will warn you about the files it could not install. + + If you DO see a warning message about files that could not be +installed, then you should manually 'diff' the files. There MAY be +changes in the dictionary files which are REQUIRED for a new version +of the software. These files will NOT be installed over your current +configuration, so you MUST verify and install any problem files by +hand. + + It is EXTREMELY helpful to read the output of both 'configure', +'make', and 'make install'. If a particular module you expected to be +installed was NOT installed, then the output of the +'configure;make;make install' sequence will tell you why that module +was not installed. Please do NOT post questions to the FreeRADIUS +users list without carefully reading the output of this process. + + +2. RUNNING THE SERVER + + If the server builds and installs, but doesn't run correctly, then +you may use debugging mode to figure out the problem. + + This is your BEST HOPE for understanding the problem. Read ALL of +the messages which are printed to the screen, the answer to your +problem will often be in a warning or error message. + + We really can't emphasize that last sentence enough. Configuring a +RADIUS server for complex local authentication isn't a trivial task. +Your ONLY method for debugging it is to read the debug messages, where +the server will tell you exactly what it's doing, and why. You should +then compare its behaviour to what you intended, and edit the +configuration files as appropriate. + + If you don't use debugging mode, then you will look dumb when you +ask questions on the 'freeradius-users' list, and the final answer +turns out to have been sitting in front of you all along. Since the +main developers of FreeRADIUS use debugging mode to track down their +configuration problems with the server, it's probably a good idea for +you to use it, too. + + To start the server in debugging mode, do: $ radiusd -X diff --git a/README b/README index 9026fd6..3703896 100644 --- a/README +++ b/README @@ -1,38 +1,59 @@ +1. INTRODUCTION - debian/ Files to build a radiusd-freeradius Debian package - doc/ Various snippets of documentation - raddb/ Sample files for /etc/raddb - scripts/ Sample scripts for startup and maintenance - src/ Source code - todo/ TODO list and assorted files. + The FreeRADIUS Server Project is a high performance and highly +configurable GPL'd free RADIUS server. The server is similar in some +respects to Livingston's 2.0 server. While FreeRADIUS started as a +variant of the Cistron RADIUS server, they don't share a lot in common +any more. It now has many more features than Cistron or Livingston, +and is much more configurable. -Please see the README and other documentation in the doc/ subdirectory + FreeRADIUS is an Internet authentication daemon, which implements +the RADIUS protocol, as defined in RFC 2865 (and others). It allows +Network Access Servers (NAS boxes) to perform authentication for +dial-up users. There are also RADIUS clients available for Web +servers, firewalls, Unix logins, and more. Using RADIUS allows +authentication and authorization for a network to be centralized, and +minimizes the amount of re-configuration which has to be done when +adding or deleting new users. + Please see the main web page (http://www.freeradius.org) for more +up-to-date information. - If you have ANY problems, concerns, or surprises when running the -server, then run it in debugging mode, as root, from the command line: +2. INSTALLATION -$ radiusd -X + To install the server, please see the INSTALL file in this +directory. -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. +3. DEBUGGING THE SERVER - For further details, see: + Run the server in debugging mode, (radiusd -X) and READ the output. +We really can't emphasize this enough. - http://www.freeradius.org/faq/ + Read the FAQ. Many questions are answered there. - and ./doc/bugs + Read the configuration files. Many parts of the server have NO +documentation, other than comments in the configuration file. + Search the mailing lists. There is a Google link on the bottom of + the page: -For more general RADIUS information, the Livington internet site had a -lot of information on radius online. Unfortunately Livingston, and + http://www.freeradius.org/list/users.html + + Type some key words into the search box, and you should find +discussions about common problems and solution. + + +4. ADDITIONAL INFORMATION + + See 'doc/README' for more information about FreeRADIUS. + + For more general RADIUS information, the Livington internet site had +a lot of information on radius online. Unfortunately Livingston, and the site, don't exist anymore but there's a copy of the site still at: http://portmasters.com/www.livingston.com/ -Especially worth a read is the "RADIUS for Unix administrators guide" + Especially worth a read is the "RADIUS for Unix administrators guide" HTML: http://portmasters.com/tech/docs/radius/1185title.html PDF: http://portmasters.com/tech/docs/pdf/radius.pdf - diff --git a/doc/README b/doc/README index cc09996..bdfd84b 100644 --- a/doc/README +++ b/doc/README @@ -1,7 +1,6 @@ - 1. INTRO - All code in this server was written from scratch. + All code in this server was written for this project. The server is mostly compatible with livingston radiusd-2.01 (no menus or s/key support though) but with more feautures, such as: @@ -29,70 +28,9 @@ 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. COMPILE - - Ignore this section (2) if you have a pre-installed binary package. - - Radiusd now has autoconf support. This means you have to run - ./configure --flags, then run make. You can set the following flags: - - --enable-shared[=PKGS] build shared libraries [default=yes] - --enable-static[=PKGS] build static libraries [default=yes] - --enable-fast-install[=PKGS] optimize for fast installation [default=yes] - --with-gnu-ld assume the C compiler uses GNU ld [default=no] - --disable-libtool-lock avoid locking (might break parallel builds) - --with-logdir=DIR Directory for logfiles [LOCALSTATEDIR/log] - --with-radacctdir=PATH Directory for detail files [LOGDIR/radacct] - --with-raddbdir=DIR Directory for config files [SYSCONFDIR/raddb] - --with-dict-nocase Make dictionary case-independant (default=yes) - --with-ascend-binary Include support for Ascend binary filter attributes (default=yes) - --with-threads Use threads, if available. (default=yes) - --with-snmp Compile in SNMP support. (default=yes) - --disable-ltdl-install Do not install libltdl - --with-static-modules=QUOTED-MODULE-LIST - --with-experimental-modules Use experimental and unstable modules. (default=no) - --enable-developer Turns on super-duper-extra-compile-warnings - when using gcc. - - To get the defaults that Cistron Radius used up to 1.5.4.3-beta18, use: - - ./configure --localstatedir=/var --sysconfdir=/etc - - That means binaries will get installed in /usr/local/{bin,sbin}, - manpages in /usr/local/man, configuration files in /etc/raddb, - and logfiles in /var/log and /var/log/radacct. - - Now type "make". The binaries will be compiled. - - Then you do a "make install". That will install the binaries, the 'man' - pages, and MAY install the configuration files. If you have not - installed a RADIUS server before, then the configuration files for - FreeRADIUS will be installed. If you already have a RADIUS server - installed, then FreeRADIUS WILL NOT over-write your current - configuration. It will warn you about the files it could not install. - - o Copy the examples in raddb to /etc/raddb and edit+rename the sample files. - o Start radiusd (using /etc/init.d/radiusd start if applicable). - - If the server builds and installs, but doesn't run correctly, then - use debugging mode to figure out the problem. (radiusd -X). This - is your BEST HOPE for understanding the problem. Read ALL of the - messages which are printed to the screen, the answer to your problem - will often be in a warning or error message. - - We really can't emphasize that enough. Configuring a RADIUS server - for complex local installations isn't a trivial task. Your ONLY - method for debugging it is to read the debug messages, where the - server tells you exactly what it's doing, and why. You should then - compare its behaviour to what you intended, and then edit the - configuration files as appropriate. - - If you don't use debugging mode, then you will look like an idiot - when you ask questions on the 'freeradius-users' list, and the final - answer turns out to have been sitting in front of you all along. - Since the main developers of FreeRADIUS use debugging mode to track - down their configuration problems with the server, it's probably a - good idea for you to use it, too. +2. INSTALLATION + + See the INSTALL file, in the parent directory. 3. CONFIGURATION FILES @@ -287,5 +225,54 @@ http://lists.cistron.nl/archives/freeradius-devel/ +6. OTHER INFORMATION + + The files in other directories are: + + debian/ Files to build a radiusd-freeradius Debian Linux package + + dialup_admin/ A PHP web front-end to manage an SQL database associated + with the server. + + doc/ Various snippets of documentation + doc/rfc/ Copies of the RFC's. If you have Perl, do a 'make' in + that directory, and look at the HTML output. + + libltdl/ Libtool platform independent library system. + + man/ Unix Manual pages for the server, configuration files, + and associated utilities. + + mibs/ SNMP Mibs for the server. + + raddb/ Sample configuration files for the server. + + redhat/ Additional files for a RedHat Linux system. + + scripts/ Sample scripts for startup and maintenance + + src/ Source code + src/main source code for the daemon and associated utilities + src/lib source code for the RADIUS library + src/include header files + src/modules dynamic plug-in modules + + 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: + +$ 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. + + For further details, see: + + http://www.freeradius.org/faq/ + + and the 'bugs' file, in this directory. + $Date$ -originally by Miquel van Smoorenburg 21-Aug-1999 -- 2.1.4