- HEAD
# latest v3.0 dev branch HEAD
- v3.0.x
-# don't include latest v3.2 dev branch HEAD (releases are below)
-# - v3.2.x
+# latest v3.2 dev branch HEAD for upcoming release
+ - v3.2.x
tags:
# don't include all v3.0 releases, antora complains as most don't
# include any antora documentation
because of misunderstanding of FreeRADIUS operations. This document
explains how the server operates.
-Normally there are 2 steps in processing authentication request coming
-from NAS in FreeRADIUS (plus additional steps to proxy request if we use
-FreeRADIUS as a proxy): authorization and authentication.
+Normally there are two steps in processing an authentication request
+coming from a NAS in FreeRADIUS: authorization and authentication.
+If we use FreeRADIUS as a proxy to re-send the request to another
+RADIUS server there will be additional steps.
=== Authorization
These dual modules are usually related to protocol-specific
attributes, such as the `pap` module for the `User-Password`
-attribute, `chap` for `CHAP-Password, `mschap` for `MS-CHAP-*`, etc.
+attribute, `chap` for `CHAP-Password`, `mschap` for `MS-CHAP-*`, etc.
=== Request Processing
** xref:contributing.adoc[Contributing]
** xref:module_interface.adoc[Module Interface]
** xref:release-method.adoc[Release Method]
+** Buffer handling
+*** xref:dbuff.adoc[Data buffers] (`dbuff` s)
+*** xref:sbuff.adoc[String buffers] (`sbuff` s)
+*** xref:sbuff-parsing.adoc[Parsing with string buffers]
+*** xref:sbuff-ng.adoc[Sbuff issues]
** xref:todo.adoc[TODO]
== Introduction
-The FreeRADIUS web site is at https://www.freeradius.org, and most
+The FreeRADIUS web site is at https://freeradius.org/, and most
information referenced in this document can be found there.
-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!
+This document 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!
== You found a bug
Where the server terminates ungracefully due to a bus error,
segmentation violation, or other memory error, you should create a new
-issue in the issue tracker https://bugs.freeradius.org, including
+issue in the issue tracker https://bugs.freeradius.org/, including
information from the debugging sections below.
-For other issues, you should first discuss them on the users list, to
+For any other issues, you should first discuss them on the
+https://freeradius.org/support/[FreeRADIUS users list], to
see if anyone can reproduce them. 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
== Core dumps
-If the server, or one of the accompanying programs core dumps, then you
+If the server (or one of the accompanying programs) core dumps, then you
should rebuild the server as follows:
```
and follow the instructions in the proceeding section.
-You can also enable the ``panic_action'' given in
+You can also enable the `panic_action` given in
`raddb/radiusd.conf`. See the comments in that file for more details
about automatically collecting gdb debugging information when the server
crashes.
If you can’t get a core dump, or the problem doesn’t result in a core
dump, you may have to run the server under gdb. To do this, ensure that
-you have symbols in the binaries (i.e. a non-stripped binary) by
+you have symbols in the binaries (i.e. a 'non-stripped' binary) by
re-building the server as described in the previous section. Then, run
the server under gdb as follows:
(gdb) thread apply all bt full
```
-If the server isn’t threaded, the ``thread apply'' section isn’t
+If the server isn’t threaded, the `thread apply` section isn’t
necessary
The output should be printed to the screen, and also sent to the
-gdb-radiusd.log file.
+`gdb-radiusd.log` file.
You should then submit the information from the log file, along with any
server output, the output of `radiusd -xv`, and information about your
crash to happen, perform the following steps:
* Log in as root.
-* Open a screen session (https://www.gnu.org/software/screen/)
-`$ screen bash`.
+* Open a https://www.gnu.org/software/screen/[screen] session: `$ screen bash`.
* Make sure FreeRADIUS is not running.
* Make sure you have all the debug symbols about, or a debugable version
-of the server installed (one built with `--enable developer`).
-* Configure screen to log to a file; Ctrl+a,h
-* Type `gdb /path/to/radius` (or /path/to/freeradius on Debian).
+of the server installed (one built with `--enable-developer` as above).
+* Configure screen to log to a file by pressing `Ctrl+a`, then `h`.
+* Type `gdb /path/to/radiusd` (or /path/to/freeradius on Debian).
* At the `(gdb)` prompt, type `run -X`.
-* Detach from screen Ctrl+a,d.
+* Detach from screen with `Ctrl+a`, `d`.
* When you notice FreeRADIUS has died, reconnect to your screen session
`$ screen -D -r`.
* At the `(gdb)` prompt type `where` or for _lots_ of info try
`thread apply all bt full`.
-* Tell screen to stop logging, Ctrl+a,h.
+* Tell screen to stop logging, `Ctrl+a`, `h`.
* Logout from screen.
FreeRADIUS Project, copyright 2019
= Semantic Patches
-Coccinelle is an open source tool that can analyze and transform C code according to specified rules creating SmPL (Semantic Patch Language) patches_. Semantic patches are much more powerful than patches or regular expressions. so, that's why we use it.
+Coccinelle is an open source tool that can analyze and transform C code according to specified rules creating SmPL (Semantic Patch Language) patches. Semantic patches are much more powerful than patches or regular expressions. so, that's why we use it.
About Coccinelle
== Comment your code
-If you don’t, you’ll be forced to debug it 6 months later, when you have no clue
+If you don’t, you’ll be forced to debug it six months later, when you have no clue
as to what it’s doing.
If someone _really_ hates you, you’ll be forced to debug un-commented code that
someone else wrote. You don’t want to do that.
-For FreeRADIUS use doxygen `@`-style comments so you get the benefits of
-https://doc.freeradius.org.
+For FreeRADIUS, use doxygen `@`-style comments so you get the
+benefits of the developer documentation site, https://doc.freeradius.org/.
== Give things reasonable names
[NOTE]
====
-GIGO is wrong. If your function gets garbage input, it should
-complain loudly and with great descriptiveness.
+GIGO, "Garbage In, Garbage Out," is wrong. If your function gets
+garbage input, it should complain loudly and with great
+descriptiveness.
====
== Write useful error messages
Having variables containing garbage values makes it easy for the code to do
garbage things. The contents of local variables are inputs to your function. See
-#3.
+xref:#_check_input_parameters_in_the_functions_you_write[#3].
It’s also nearly impossible for you to debug any problems, as you can’t tell the
variables with garbage values from the real ones.
due to broken system header files, though. But the more warnings the merrier.
Getting error messages at compile time is much preferable to getting core dumps
-at run time. See #7.
+at run time. See xref:#_initialize_your_variables[#7].
Notice that the C compiler error messages are helpful? You should write error
-messages like this, too. See #4.
+messages like this, too. See xref:#_write_useful_error_messages[#4].
== Avoid UNIXisms and ASCIIisms and visualisms
Though it’s legal to test `if (foo) {}` if you test against the appropriate
value (like `NULL` or `'\0'`), your code is prettier and easier for others to
read without having to eyeball your prototypes continuously to figure out what
-you’re doing (especially if your variables aren’t well-named). See #2.
+you’re doing (especially if your variables aren’t well-named). See
+xref:#_give_things_reasonable_names[#2].
== Test your code
== Read the Documentation and follow the CodingStyle
The FreeRADIUS server has a common coding style. Use real tabs to indent. There
-is whitespace in variable assignments. (`i = 1`, not `i=1`).
+is whitespace in variable assignments (`i = 1`, not `i=1`).
When in doubt, format your code to look the same as code already in the server.
If your code deviates too much from the current style, it is likely to be
Code cluttered with `#ifdef` s is difficult to read and maintain. Don’t do it.
Instead, put your `#ifdef` s in a header, and conditionally define `static
inline` functions, or macros, which are used in the code. Let the compiler
-optimize away the ``no-op'' case.
+optimize away the 'no-op' case.
Simple example, of poor code:
they are as cheap as macros.
Macros should only be used for cases where a static inline is clearly suboptimal
-[there a few, isolated cases of this in fast paths], or where it is impossible
-to use a static inline function [such as string-izing].
+(there a few, isolated cases of this in fast paths), or where it is impossible
+to use a static inline function (such as string-izing).
-`static inline` is preferred over `static __inline__`, `extern inline`, and
-`extern __inline__`.
+`static inline` is preferred over `$$static __inline__$$`, `extern inline`, and
+`$$extern __inline__$$`.
== Don’t over-design
Note: Only trivial patches will be accepted via email. Large patches, or
patches that modify a number of files MUST be submitted as a
-pull-request via GitHub.
+https://github.com/FreeRADIUS/freeradius-server/pulls[pull-request via GitHub].
== Hints and tips
includes updates for subsystem X. Please apply."
If your description starts to get long, that’s a sign that you probably
-need to split up your commit. See #3, next.
+need to split up your commit. See the next point.
=== 2. Separate your changes
List with some usual howtos for FreeRADIUS.
+Programming reference documentation can be found at the
+https://doc.freeradius.org/[Doxygen] site.
+
== Topics
* xref:bugs.adoc[Bugs]
* xref:profile.adoc[Profiling]
* xref:coccinelle.adoc[Semantic Patches]
* xref:contributing.adoc[Contributing]
-* xref:installation:dependencies.adoc[Build dependencies]
* xref:module_interface.adoc[Module Interface]
* xref:release-method.adoc[Release Method]
+* Buffer handling
+** xref:dbuff.adoc[Data buffers] (`dbuff` s)
+** xref:sbuff.adoc[String buffers] (`sbuff` s)
+** xref:sbuff-parsing.adoc[Parsing with string buffers]
+** xref:sbuff-ng.adoc[Sbuff issues]
* xref:todo.adoc[TODO]
+
+Also see the xref:installation:dependencies.adoc[build
+dependencies] page.
projects / thirdparty / freeradius-server.git / commitdiff
