INSTALL

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