summaryrefslogtreecommitdiffstats
path: root/INSTALL.rst
diff options
context:
space:
mode:
Diffstat (limited to 'INSTALL.rst')
-rw-r--r--INSTALL.rst169
1 files changed, 169 insertions, 0 deletions
diff --git a/INSTALL.rst b/INSTALL.rst
new file mode 100644
index 0000000..6edb34d
--- /dev/null
+++ b/INSTALL.rst
@@ -0,0 +1,169 @@
+Installation
+============
+
+1. INTRODUCTION
+---------------
+
+Ignore the installation instructions in this file if you have a
+pre-installed binary package. When upgrading from older versions of
+FreeRADIUS, you should read ALL of this file, especially the section
+on "UPGRADING" below which gives information on how to update your
+configuration.
+
+Whether you are installing from source or a pre-built binary
+package, you should read the section below "RUNNING THE SERVER".
+
+
+2. SIMPLE INSTALLATION
+----------------------
+
+If you do not need to modify the default configuration, then take
+the following steps to build and install the server::
+
+ $ ./configure
+ $ make
+ $ make install
+
+
+3. 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]
+ --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)
+ --with-dhcp Compile in DHCP support. (default=yes)
+ --with-experimental-modules Use experimental and unstable modules.
+ (default=no)
+ --enable-developer Turns on super-duper-extra-compile-warnings
+ when using gcc, as well as experimental modules.
+
+The ``make install`` stage 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.**
+
+The ``make install`` process will warn you about the files it could
+not install.
+
+If you see a warning message about files that could not be
+installed, then you MUST ensure that the new server is using the new
+configuration files, and not the old configuration files. The initial
+output from running in debugging mode (``radiusd -X``) will tell you which
+configuration files are being used. See UPGRADING above for
+information about upgrading from older versions. 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, for example using ``diff(1)`` to check for changes.
+
+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 first carefully reading the output of this process.
+
+
+4. UPGRADING
+------------
+
+The installation process will not over-write your existing
+configuration files. It will, however, warn you about the files it
+did not install.
+
+For users upgrading from any older version to 3.0, it is *NOT*
+possible to use the older configuration as-is. However, the version
+2.x configuration is largely compatible, so upgrading the
+configuration should not be too difficult. For details on what has
+changed, see ``raddb/README.rst``.
+
+We STRONGLY recommend that 3.0 be installed in a different location
+than any existing 1.x or 2.x installation. Any local policies can
+then be migrated gradually to the new 3.0 configuration. The number
+of differences in the new configuration mean that is is both simpler
+and safer to migrate your configurations rather than to try and just
+get the old configuration to work.
+
+
+5. RUNNING THE SERVER
+---------------------
+
+If the server builds and installs, but doesn't run correctly, then
+you should use debugging mode (radiusd -X) 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, and ask questions on the mailing
+list, then the responses will all tell you to use debugging mode. The
+server prints out a lot of information in this mode, including
+suggestions for fixes to common problems. Look especially for
+"WARNING" in the output, and read the related messages.
+
+Since the main developers of FreeRADIUS use debugging mode to track
+down their configuration problems with the server, it's a good idea
+for you to use it, too. If you don't, there is little hope for you to
+solve ANY configuration problem related to the server.
+
+To start the server in debugging mode, do::
+
+ $ radiusd -X
+
+You should see a lot of text printed on the screen as it starts up.
+If you don't, or if you see error messages, please read the FAQ:
+
+ http://www.freeradius.org/faq/
+
+If the server says "Ready to process requests.", then it is running
+properly. From another shell (or another window), type::
+
+ $ radtest test test localhost 0 testing123
+
+You should see the server print out more messages as it receives the
+request, and responds to it. The 'radtest' program should receive the
+response within a few seconds. It doesn't matter if the
+authentication request is accepted or rejected, what matters is that
+the server received the request, and responded to it.
+
+You can now edit the configuration files for your local system. You
+will usually want to start with ``sites-enabled/default``. To set
+which NASes (clients) can communicate with this server,
+edit ``clients.conf``.
+Please read the configuration files carefully, as many configuration
+options are only documented in comments in the file.
+
+Note that is is HIGHLY recommended that you use some sort of version
+control system to manage your configuration, such as git or
+Subversion. You should then make small changes to the configuration,
+checking in and testing as you go. When a config change causes the
+server to stop working, you will be able to easily step back and find
+out what update broke the configuraiton.
+
+Configuring and running the server MAY be complicated. Many modules
+have ``man`` pages. See ``man rlm_pap``, or ``man rlm_*`` for
+information.
+Please read the documentation in the doc/ directory. The comments in
+the configuration files also contain a lot of documentation.
+
+If you have any additional issues, the FAQ is also a good place to
+start.
+