INSTALL.rst

   1 Installation
   2 ============
   3
   4 1. INTRODUCTION
   5 ---------------
   6
   7 Ignore the installation instructions in this file if you have a
   8 pre-installed binary package.  When upgrading from older versions of
   9 FreeRADIUS, you should read ALL of this file, especially the section
  10 on "UPGRADING" below which gives information on how to update your
  11 configuration.
  12
  13 Whether you are installing from source or a pre-built binary
  14 package, you should read the section below "RUNNING THE SERVER".
  15
  16
  17 2. SIMPLE INSTALLATION
  18 ----------------------
  19
  20 If you do not need to modify the default configuration, then take
  21 the following steps to build and install the server::
  22
  23   $ ./configure
  24   $ make
  25   $ make install
  26
  27
  28 3. CUSTOM INSTALLATION
  29 ----------------------
  30
  31 FreeRADIUS has autoconf support. This means you have to run
  32 ``./configure``, and then run make.  To see which configuration options
  33 are supported, run ``./configure --help``, and read it's output.  The
  34 following list is a selection from the available flags::
  35
  36   --enable-shared[=PKGS]  build shared libraries [default=yes]
  37   --enable-static[=PKGS]  build static libraries [default=yes]
  38   --with-logdir=DIR       Directory for logfiles [LOCALSTATEDIR/log]
  39   --with-radacctdir=PATH  Directory for detail files [LOGDIR/radacct]
  40   --with-raddbdir=DIR     Directory for config files [SYSCONFDIR/raddb]
  41   --with-threads          Use threads, if available.  (default=yes)
  42   --with-snmp             Compile in SNMP support. (default=yes)
  43   --with-dhcp             Compile in DHCP support. (default=yes)
  44   --with-experimental-modules  Use experimental and unstable modules.
  45                                (default=no)
  46   --enable-developer      Turns on super-duper-extra-compile-warnings
  47                           when using gcc, as well as experimental modules.
  48
  49 The ``make install`` stage will install the binaries, the 'man' pages,
  50 and MAY install the configuration files.  If you have not installed a
  51 RADIUS server before, then the configuration files for FreeRADIUS will
  52 be installed.  If you already have a RADIUS server installed, then
  53
  54 **FreeRADIUS WILL NOT over-write your current configuration.**
  55
  56 The ``make install`` process will warn you about the files it could
  57 not install.
  58
  59 If you see a warning message about files that could not be
  60 installed, then you MUST ensure that the new server is using the new
  61 configuration files, and not the old configuration files.  The initial
  62 output from running in debugging mode (``radiusd -X``) will tell you which
  63 configuration files are being used.  See UPGRADING above for
  64 information about upgrading from older versions.  There MAY be changes
  65 in the dictionary files which are REQUIRED for a new version of the
  66 software.  These files will NOT be installed over your current
  67 configuration, so you MUST verify and install any problem files by
  68 hand, for example using ``diff(1)`` to check for changes.
  69
  70 It is EXTREMELY helpful to read the output of both ``./configure``,
  71 ``make``, and ``make install``.  If a particular module you expected to be
  72 installed was not installed, then the output of the
  73 ``./configure; make; make install`` sequence will tell you why that module
  74 was not installed.  Please do NOT post questions to the FreeRADIUS
  75 users list without first carefully reading the output of this process.
  76
  77
  78 4. UPGRADING
  79 ------------
  80
  81 The installation process will not over-write your existing
  82 configuration files.  It will, however, warn you about the files it
  83 did not install.
  84
  85 For users upgrading from any older version to 3.0, it is *NOT*
  86 possible to use the older configuration as-is. However, the version
  87 2.x configuration is largely compatible, so upgrading the
  88 configuration should not be too difficult.  For details on what has
  89 changed, see ``raddb/README.rst``.
  90
  91 We STRONGLY recommend that 3.0 be installed in a different location
  92 than any existing 1.x or 2.x installation.  Any local policies can
  93 then be migrated gradually to the new 3.0 configuration.  The number
  94 of differences in the new configuration mean that is is both simpler
  95 and safer to migrate your configurations rather than to try and just
  96 get the old configuration to work.
  97
  98
  99 5. RUNNING THE SERVER
 100 ---------------------
 101
 102 If the server builds and installs, but doesn't run correctly, then
 103 you should use debugging mode (radiusd -X) to figure out the problem.
 104
 105 This is your BEST HOPE for understanding the problem.  Read ALL of
 106 the messages which are printed to the screen, the answer to your
 107 problem will often be in a warning or error message.
 108
 109 We really can't emphasize that last sentence enough.  Configuring a
 110 RADIUS server for complex local authentication isn't a trivial task.
 111 Your ONLY method for debugging it is to read the debug messages, where
 112 the server will tell you exactly what it's doing, and why.  You should
 113 then compare its behaviour to what you intended, and edit the
 114 configuration files as appropriate.
 115
 116 If you don't use debugging mode, and ask questions on the mailing
 117 list, then the responses will all tell you to use debugging mode.  The
 118 server prints out a lot of information in this mode, including
 119 suggestions for fixes to common problems.  Look especially for
 120 "WARNING" in the output, and read the related messages.
 121
 122 Since the main developers of FreeRADIUS use debugging mode to track
 123 down their configuration problems with the server, it's a good idea
 124 for you to use it, too.  If you don't, there is little hope for you to
 125 solve ANY configuration problem related to the server.
 126
 127 To start the server in debugging mode, do::
 128
 129   $ radiusd -X
 130
 131 You should see a lot of text printed on the screen as it starts up.
 132 If you don't, or if you see error messages, please read the FAQ:
 133
 134   http://www.freeradius.org/faq/
 135
 136 If the server says "Ready to process requests.", then it is running
 137 properly.  From another shell (or another window), type::
 138
 139   $ radtest test test localhost 0 testing123
 140
 141 You should see the server print out more messages as it receives the
 142 request, and responds to it.  The 'radtest' program should receive the
 143 response within a few seconds.  It doesn't matter if the
 144 authentication request is accepted or rejected, what matters is that
 145 the server received the request, and responded to it.
 146
 147 You can now edit the configuration files for your local system. You
 148 will usually want to start with ``sites-enabled/default``. To set
 149 which NASes (clients) can communicate with this server,
 150 edit ``clients.conf``.
 151 Please read the configuration files carefully, as many configuration
 152 options are only documented in comments in the file.
 153
 154 Note that is is HIGHLY recommended that you use some sort of version
 155 control system to manage your configuration, such as git or
 156 Subversion. You should then make small changes to the configuration,
 157 checking in and testing as you go. When a config change causes the
 158 server to stop working, you will be able to easily step back and find
 159 out what update broke the configuraiton.
 160
 161 Configuring and running the server MAY be complicated.  Many modules
 162 have ``man`` pages.  See ``man rlm_pap``, or ``man rlm_*`` for
 163 information.
 164 Please read the documentation in the doc/ directory.  The comments in
 165 the configuration files also contain a lot of documentation.
 166
 167 If you have any additional issues, the FAQ is also a good place to
 168 start.
 169