Adding upstream version 3.2.1+dfsg.upstream/3.2.1+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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.
+