INSTALL

   1 1. INSTALLATION
   2
   3   Ignore this file if you have a pre-installed binary package.
   4
   5
   6 1a. 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 1b. CUSTOM INSTALLATION
  27
  28   FreeRADIUS has autoconf support. This means you have to run
  29 ./configure, and then run make.  To see which configuration options
  30 are supported, run './configure --help', and read it's output.  The
  31 following list is a selection from the available flags:
  32
  33   --enable-shared[=PKGS]  build shared libraries [default=yes]
  34   --enable-static[=PKGS]  build static libraries [default=yes]
  35   --enable-fast-install[=PKGS]  optimize for fast installation [default=yes]
  36   --with-logdir=DIR       Directory for logfiles [LOCALSTATEDIR/log]
  37   --with-radacctdir=PATH  Directory for detail files [LOGDIR/radacct]
  38   --with-raddbdir=DIR     Directory for config files [SYSCONFDIR/raddb]
  39   --with-threads          Use threads, if available.  (default=yes)
  40   --with-snmp             Compile in SNMP support. (default=yes)
  41   --disable-ltdl-install  Do not install libltdl
  42   --with-experimental-modules      Use experimental and unstable modules. (default=no)
  43   --enable-developer      Turns on super-duper-extra-compile-warnings
  44                               when using gcc.
  45   --with-edir             Compile with support for Novell eDirectory
  46                               integration.
  47
  48   The "make install" stage will install the binaries, the 'man' pages,
  49 and MAY install the configuration files.  If you have not installed a
  50 RADIUS server before, then the configuration files for FreeRADIUS will
  51 be installed.  If you already have a RADIUS server installed, then
  52 FreeRADIUS WILL NOT over-write your current configuration.  The "make
  53 install" process will warn you about the files it could not install.
  54
  55   If you DO see a warning message about files that could not be
  56 installed, the it is YOUR RESPONSIBILITY to ensure that the new server
  57 is using the new configuration files, and not the old configuration
  58 files.  You may need to manually 'diff' the files.  There MAY be
  59 changes in the dictionary files which are REQUIRED for a new version
  60 of the software.  These files will NOT be installed over your current
  61 configuration, so you MUST verify and install any problem files by
  62 hand.
  63
  64   It is EXTREMELY helpful to read the output of both 'configure',
  65 'make', and 'make install'.  If a particular module you expected to be
  66 installed was not installed, then the output of the
  67 'configure;make;make install' sequence will tell you why that module
  68 was not installed.  Please do NOT post questions to the FreeRADIUS
  69 users list without carefully reading the output of this process.
  70
  71
  72 2. RUNNING THE SERVER
  73
  74   If the server builds and installs, but doesn't run correctly, then
  75 you may use debugging mode (radiusd -X) to figure out the problem.
  76
  77   This is your BEST HOPE for understanding the problem.  Read ALL of
  78 the messages which are printed to the screen, the answer to your
  79 problem will often be in a warning or error message.
  80
  81   We really can't emphasize that last sentence enough.  Configuring a
  82 RADIUS server for complex local authentication isn't a trivial task.
  83 Your ONLY method for debugging it is to read the debug messages, where
  84 the server will tell you exactly what it's doing, and why.  You should
  85 then compare its behaviour to what you intended, and edit the
  86 configuration files as appropriate.
  87
  88   If you don't use debugging mode, and ask questions on the mailing
  89 list, then the responses will all tell you to use debugging mode.  The
  90 server prints out a lot of information in this mode, including
  91 suggestions for fixes to common problems.  Look for "WARNING" in the
  92 output, and read the related messages.
  93
  94    Since the main developers of FreeRADIUS use debugging mode to track
  95 down their configuration problems with the server, it's a good idea
  96 for you to use it, too.  If you don't, there is little hope for you to
  97 solve ANY configuration problem related to the server.
  98
  99   To start the server in debugging mode, do:
 100
 101         $ radiusd -X
 102
 103   You should see a lot of text printed on the screen as it starts up.
 104 If you don't, or if you see error messages, please read the FAQ:
 105
 106         http://www.freeradius.org/faq/
 107
 108   If the server says "Ready to process requests.", then it is running
 109 properly.  From another shell (or another window), type:
 110
 111         $ radtest test test localhost 0 testing123
 112
 113   You should see the server print out more messages as it receives the
 114 request, and responds to it.  The 'radtest' program should receive the
 115 response within a few seconds.  It doesn't matter if the
 116 authentication request is accepted or rejected, what matters is that
 117 the server received the request, and responded to it.
 118
 119   You can now edit the 'radiusd.conf' file for your local system.
 120 Please read the ENTIRE file carefully, as many configuration options
 121 are only documented in comments in the file.
 122
 123   Configuring and running the server MAY be complicated.  Many modules
 124 have "man" pages.  See "man rlm_pap", or "man rlm_*" for information.
 125 Please read the documentation in the doc/ directory.  The comments in
 126 the configuration files also contain a lot of documentation.
 127
 128   If you have any additional issues, the FAQ is also a good place to
 129 check.