GNU Radius README Copyright (C) 2002, 2003, 2004, 2008, 2010, 2013 Free Software Foundation, Inc. See the end of file for copying conditions. * Introduction This file contains brief information about configuring, testing and running GNU Radius. It is *not* intended as a replacement for the documentation, it is provided as a brief reference only. The complete documentation for GNU Radius is available in doc/texinfo subdirectory. To read it without installing the package run `info -f doc/texinfo/radius'. After the package is installed the documentation can be accessed running `info radius'. The online copy of the documentation in various formats is available at http://www.gnu.org/software/radius/manual. * Installation Before installing, take a glance at doc/MACHINES, it may describe some issues, specific to your configuration. If you are upgrading from a previous version of GNU Radius, make sure to read the section `Upgrading from earlier versions' below. To install the package, do: ** ./configure [options] For the list of available options consult file INSTALL. The applications-specific options are: *** --disable-debug Disable debugging functions. This results in slightly more compact code, but makes configuration issues difficult to debug. Use at your own risk. *** --with-auth-port=NUMBER Specify port number to use for authentication. Default is 1812. The default port number for accounting is computed as auth_port + 1. *** --enable-pam Enable PAM support. *** --enable-dbm[={dbm|ndbm}] Enable dbm support. If no argument is specified, usual DBM is assumed. The `ndbm' argument instructs to enable support of NDBM. *** --with-mysql Enable MySQL support. Usually this requires setting appropriate values for LDFLAGS and CPPFLAGS variables. *** --with-postgres Enable PostgreSQL support. Usually this requires setting appropriate values for LDFLAGS and CPPFLAGS variables. *** --with-odbc[={odbc|iodbc}] Configure to work with ODBC. This is an experimental feature, it has not been tested thoroughly. *** --without-guile Do not compile Guile support. *** --without-server-guile Do not compile server Guile support *** --enable-client Build client programs. Requires presence of Guile >=1.6 and PAM on your system. *** --disable-server Do not build radius server. This implies --enable-client. *** --with-readline Enable GNU readline support for radiusd test shell mode. *** --without-readline Disable GNU readline support *** --with-php=PHP-PREFIX Compile mod_radius php module. PHP-PREFIX is the path where php is installed. The module requires php 4.3.x *** --enable-snmp[=compat] Enable SNMP support. By default this enables the use of enterprise subtree .iso.org.dod.internet.private.enterprises.gnu.radius (.1.3.6.1.4.1.11591.1). To enable support for the subtree used in previous versions of radius (i.e. .iso.org.dod.internet.private.enterprises.gnu-radius = .1.3.6.1.4.1.9163) use --enable-snmp=compat form of this option. *** --enable-livingston-menus Enable support for Livingston-compatible menus. *** --enable-deny-shell=SHELL Always reject users with the given shell. *** --with-pamdir=DIR Install PAM modules in the given DIR. Default is $prefix/lib/security. *** --with-log-dir=DIRNAME Specifies the full pathname to the default logging directory. By default it is either /var/log or /usr/adm, whichever is applicable to your operationg system and directory layout. *** --with-pid-dir=DIRNAME Specifies the full pathname to the directory where radiusd will store its pid-file (radiusd.pid). Default is either "/var/run", or, if this directory does not exist, "$sysconfdir/raddb". ** Run make. The GNU make is preferred. ** Check it. You can check the functionality of the package without installing it. To do so, run make check (You have to have DejaGNU installed on your system). ** Run `make install' * Creating SQL database. If you have configured Radius with SQL support, you may wish to create the authentication and accounting database. Notice, that if you already have a running database, you may continue using it with GNU Radius. You will only have to modify file raddb/sqlserver to match your database structure. To create a fresh Radius database, follow the procedure below: ** Change to the subdirectory db/ ** Edit file config.m4. Most of its contents is commented out, so uncomment anything that may be needed. Variables are: server - SQL server name or IP address port - port to connect to User credentials for creator of the database: CREATOR - SQL username. This user must have create privileges. CREATOR_PASSWORD - SQL password. User credentials for the owner of the database: DB_USER - SQL username. DB_PWD - SQL password. (These must coincide with the values in raddb/sqlserver file) ** Depending on the type of SQL server you are using, run either `make mysql' or `make pgsql'. To get the database structure without creating it, run `make mysql.struct' or `make pgsql.struct'. * Upgrading from earlier versions of GNU Radius Please, read file NEWS. It contains important information about upgrading from earlier versions, as well as an exhaustive list of all the new features. * Configuring Be sure to read the accompanying documentation. The online documentation is available at http://www.gnu.org/software/radius/manual. If you need help, subscribe to and send your questions there. To subscribe, visit http://mail.gnu.org/mailman/listinfo/help-gnu-radius Before asking a question, it will be a good idea to look through the mailing archives on the same page, as they might already contain the answer. * Testing. The commands described below use the configuration file raddb/client.conf. See the documentation for the detailed description of this file. The default raddb/client.conf installed from the distribution should suffice to test the server in default configuration. ** Using radauth Use radauth to send various radius requests to the running server. The invocation syntax is: radauth [OPTIONS] [COMMAND] username [pass] OPTIONS are: -v Print verbose descriptions of what is being done -n IP Set NAS IP address -s SID Set session ID -P PORT Set NAS port number COMMAND is one of: auth Send only Access-Request (default) acct Send Access-Request. If successfull, send accounting start request start Send accounting start request stop Send accounting stop request So, to test authentication, run: radauth LOGIN PASSWD You may omit PASSWD if you wish to prevent the password from being compromised. In this case, radauth will disable echoing on the screen, prompt you for the password, and turn the echoing on again. To test accounting, use radauth -s SID -P PORT start LOGIN or radauth -s SID -P PORT stop LOGIN Options may be omitted. Radauth will prompt you for the value of any missing option, e.g.: $ radauth start gray Enter session ID: a001 Enter NAS port ID: 1 To fully simulate actions of a NAS when initiating user session, use acct command: radauth -s SID -P PORT acct LOGIN PASSWD Again, you may omit options as well as PASSWD. ** Using radsession If you have guile version 1.6.4 or better installed, you can use radsession script to send authentication/accounting requests to the server. *** Authentication test radsession -l LOGIN -p PASSWD -P PORT-ID --auth *** Accounting test To test accounting do: radsession -l LOGIN -p PASSWD -P PORT-ID -s SESSION-ID --start or radsession -l LOGIN -P PORT-ID -s SESSION-ID --stop Where: LOGIN is the user's login name PASSWD is his password. Use `.' (dot) to get prompted for the password as passwd(1) does. PORT-ID is the port number SESSION-ID is a session ID (a string uniquely identifying the session). It can be an arbitrary string when used with --start option. It should be a session ID of a previously started session when used with --stop option. ** Examples using radauth and radsession The examples below assume that you have your radius server up and running, your user database contains a record for user `hamlet' with password `guessme'. The examples show two alternative variants of testing commands: using radauth command and using radsession. To authenticate `hamlet' and start a radius session, invoke: radauth -P 1 -s 0001 acct hamlet guessme or radsession -l hamlet -p guessme -P 1 -s 0001 --start Now, if you run radwho, you will get something like: Login Name What TTY When From Location hamlet hamlet PPP S001 Mon 07:22 localhost 255.255.255.254 whereas radlast will show the following; hamlet local 001 127.0.0.2 Thu Mon 07 07:22 - still logged in radwtmp begins Fri Dec 01 16:36:59 2000 Then, suppose you run: radauth -P 1 -s 0001 stop hamlet or radsession -l hamlet -P 1 -s 0001 --stop This will send a stop record for session 0001. Radlast will then show something like: hamlet local 001 127.0.0.2 Thu Mon 07 07:22 - 07:25 (00:03) radwtmp begins Fri Dec 01 16:36:59 2000 ** Using radtest Radtest is a radius client shell providing simple yet powerful scripting language and allowing to send arbitrary radius requests and analize server replies. It allows you to write sophisticated procedures for interacting with the remote servers. It is not designed for newbies, so use it if you wish to test some non-standard configurations. See accompanying documentation (chapter "Radtest") for the detailed description of the tool. * Bug reporting. Send bug reports to . * Copyright information: Copyright (C) 2002, 2003, 2004, 2008, 2010, 2013 Free Software Foundation, Inc. Permission is granted to anyone to make or distribute verbatim copies of this document as received, in any medium, provided that the copyright notice and this permission notice are preserved, thus giving the recipient permission to redistribute in turn. Permission is granted to distribute modified versions of this document, or of portions of it, under the above conditions, provided also that they carry prominent notices stating who last changed them. Local Variables: mode: outline paragraph-separate: "[ ]*$" version-control: never End: