
( The FreeRADIUS web site is at <URL: http://www.freeradius.org/>, and
most information referenced in this document can be found there.  A web
interface to the BTS can be found at <URL: http://bugs.freeradius.org/>.)

This is primarily for non-developers of the FreeRADIUS server.  If you are
able to patch the code to work correctly, then we invite you to join the 
development list to discuss it.  If you're the type who know little about
how to code, then this is the place for you!


= So you think you've found a bug in the FreeRADIUS server

You should first discuss it on the users list, to see if anyone can repro-
duce it.  Often there's a simple explanation of why the server behaves as
it does, and it's not necessarily a bug in the code, so browse the lists'
archives of the last two months, and if you don't see messages about it,
ask!

If the behavior is correct but confusing, we think that's a bug too, and
you should file a bug against our documentation.


= Looking at core dumps

If the server, or one of the accompyaning programs core dumps, then
you should rebuild the server as follows:

$ ./configure --enable-developer
$ make
$ make install

  and then run the program again.  When it core dumps, do:

$ gdb /path/to/executable /path/to/core/file

  And then in 'gdb', do:

$ bt

  Copy the output, and mail it to the list, along with the name of the
program you were running, and the name of the operating system.
Without this information, it's impossible for anyone to know why the
program core dumped.


= Filing a bug report

If you see something that's obviously a bug, and the developers agree,
then you should keep 'em from forgetting about it by filing a bug report.
Using the bug-tracking system (often called 'BTS') is rather easy, once
one understands how it works.

Since few (if any!) of the developers have ever met each other in real
life, it's sensible to use the only communication method everyone is
accustomed to; the BTS uses email messages to do _everything_.

Don't send HTML or any attachments, please.  If you don't know what this
means, and you're using some mailer like Netscape Communicator or
Microsoft Outlook, please ask someone first.  No HTML.  No Rich-text.  No
GPG/PGP signed messages.  No vcards.   ** Plain text only! **

To submit a bug report, you should mail 'submit@bugs.freeradius.org' with
a well-defined structure in the body:  First a header, then a description.

The first non-empty line in the body of the message should describe what
part of the project needs help, using the "Package: " line.  What follows
"Package: " should be nothing but one of the following words:
  core             -- the main server
  rlm              -- about modules
  documentation
  bts              -- bug-tracking problem, suggestions
  website

After that, you should put a few empty lines, and then describe what the
problem is and how you think it could best be fixed.  Include exact error
messages, and don't assume the developers know _anything_ about what OS or
environment you're using.

Mailing 'submit' is ONLY for submission of NEW reports.  If you have
follow-up information and you know the bug number, mail
BUGNUMBER@bugs.freeradius.org (replacing BUGNUMBER with the actual bug
number, of course).

--

Chad Miller, FreeRADIUS Project, copyright 2001
$Revision: 1.2 $
