INSTALL

   1 1. INSTALLATION
   2
   3   Ignore this file if you have a pre-installed binary package.
   4
   5
   6 2. SIMPLE INSTALLATION
   7
   8   If you do not need to modify the default configuration, then take
   9 the following steps to build and install the server:
  10
  11
  12         $ ./configure
  13         $ make
  14         $ make install
  15
  16   The first time after installation, you should run the server as
  17 "root".  This will cause the server to create the certificates it
  18 needs for EAP.
  19
  20         $ radiusd -X
  21
  22   Once that is done, the server can be run from an unpriviledged user
  23 account.
  24
  25
  26 3. UPGRADING
  27
  28   The installation process will not over-write your existing
  29 configuration files.  It will, however, warn you about the files it
  30 did not install.
  31
  32   For users upgrading from 1.x to 2.0, we STRONGLY recommend that 2.0
  33 be installed in a different location than the existing 1.x
  34 installation.  Any local policies can then be migrated gradually to
  35 the new 2.0 configuration.  While we have put a lot of time into
  36 ensuring that 2.0 is mostly backwards compatible with 1.x, it is not
  37 COMPLETELY backwards compatible.  There are differences that mean it
  38 is simpler and safer to migrate your configurations.
  39
  40   If you are upgrading an existing installation, please be aware that
  41 at least one default virtual server MUST be used.  If you are
  42 upgrading from a previous version of FreeRADIUS, this change can be
  43 done by editing radiusd.conf, and wrapping all of the authorize,
  44 authenticate, etc. sections in one server block, as follows:
  45
  46 ...
  47   server {      # line to add
  48         authorize {
  49                 ...
  50         }
  51         authenticate {
  52                 ...
  53         }
  54         accounting {
  55                 ...
  56         }
  57         ...
  58         post-proxy {
  59                 ...
  60         }
  61   }             # matching line to add
  62 ...
  63
  64   If this change is not made, the server WILL NOT START.  It will
  65 instead complain about "no server defined".
  66
  67   See "raddb/sites-available/default" for an example of how this
  68 should be done.
  69
  70
  71 4. CUSTOM INSTALLATION
  72
  73   FreeRADIUS has autoconf support. This means you have to run
  74 ./configure, and then run make.  To see which configuration options
  75 are supported, run './configure --help', and read it's output.  The
  76 following list is a selection from the available flags:
  77
  78   --enable-shared[=PKGS]  build shared libraries [default=yes]
  79   --enable-static[=PKGS]  build static libraries [default=yes]
  80   --enable-fast-install[=PKGS]  optimize for fast installation [default=yes]
  81   --with-logdir=DIR       Directory for logfiles [LOCALSTATEDIR/log]
  82   --with-radacctdir=PATH  Directory for detail files [LOGDIR/radacct]
  83   --with-raddbdir=DIR     Directory for config files [SYSCONFDIR/raddb]
  84   --with-threads          Use threads, if available.  (default=yes)
  85   --with-snmp             Compile in SNMP support. (default=yes)
  86   --disable-ltdl-install  Do not install libltdl
  87   --with-experimental-modules      Use experimental and unstable modules. (default=no)
  88   --enable-developer      Turns on super-duper-extra-compile-warnings
  89                               when using gcc.
  90   --with-edir             Compile with support for Novell eDirectory
  91                               integration.
  92
  93   The "make install" stage will install the binaries, the 'man' pages,
  94 and MAY install the configuration files.  If you have not installed a
  95 RADIUS server before, then the configuration files for FreeRADIUS will
  96 be installed.  If you already have a RADIUS server installed, then
  97 FreeRADIUS WILL NOT over-write your current configuration.  The "make
  98 install" process will warn you about the files it could not install.
  99
 100   If you DO see a warning message about files that could not be
 101 installed, the it is YOUR RESPONSIBILITY to ensure that the new server
 102 is using the new configuration files, and not the old configuration
 103 files.  You may need to manually 'diff' the files.  There MAY be
 104 changes in the dictionary files which are REQUIRED for a new version
 105 of the software.  These files will NOT be installed over your current
 106 configuration, so you MUST verify and install any problem files by
 107 hand.
 108
 109   It is EXTREMELY helpful to read the output of both 'configure',
 110 'make', and 'make install'.  If a particular module you expected to be
 111 installed was not installed, then the output of the
 112 'configure;make;make install' sequence will tell you why that module
 113 was not installed.  Please do NOT post questions to the FreeRADIUS
 114 users list without carefully reading the output of this process.
 115
 116
 117 2. RUNNING THE SERVER
 118
 119   If the server builds and installs, but doesn't run correctly, then
 120 you may use debugging mode (radiusd -X) to figure out the problem.
 121
 122   This is your BEST HOPE for understanding the problem.  Read ALL of
 123 the messages which are printed to the screen, the answer to your
 124 problem will often be in a warning or error message.
 125
 126   We really can't emphasize that last sentence enough.  Configuring a
 127 RADIUS server for complex local authentication isn't a trivial task.
 128 Your ONLY method for debugging it is to read the debug messages, where
 129 the server will tell you exactly what it's doing, and why.  You should
 130 then compare its behaviour to what you intended, and edit the
 131 configuration files as appropriate.
 132
 133   If you don't use debugging mode, and ask questions on the mailing
 134 list, then the responses will all tell you to use debugging mode.  The
 135 server prints out a lot of information in this mode, including
 136 suggestions for fixes to common problems.  Look for "WARNING" in the
 137 output, and read the related messages.
 138
 139    Since the main developers of FreeRADIUS use debugging mode to track
 140 down their configuration problems with the server, it's a good idea
 141 for you to use it, too.  If you don't, there is little hope for you to
 142 solve ANY configuration problem related to the server.
 143
 144   To start the server in debugging mode, do:
 145
 146         $ radiusd -X
 147
 148   You should see a lot of text printed on the screen as it starts up.
 149 If you don't, or if you see error messages, please read the FAQ:
 150
 151         http://www.freeradius.org/faq/
 152
 153   If the server says "Ready to process requests.", then it is running
 154 properly.  From another shell (or another window), type:
 155
 156         $ radtest test test localhost 0 testing123
 157
 158   You should see the server print out more messages as it receives the
 159 request, and responds to it.  The 'radtest' program should receive the
 160 response within a few seconds.  It doesn't matter if the
 161 authentication request is accepted or rejected, what matters is that
 162 the server received the request, and responded to it.
 163
 164   You can now edit the 'radiusd.conf' file for your local system.
 165 Please read the ENTIRE file carefully, as many configuration options
 166 are only documented in comments in the file.
 167
 168   Configuring and running the server MAY be complicated.  Many modules
 169 have "man" pages.  See "man rlm_pap", or "man rlm_*" for information.
 170 Please read the documentation in the doc/ directory.  The comments in
 171 the configuration files also contain a lot of documentation.
 172
 173   If you have any additional issues, the FAQ is also a good place to
 174 check.