From: Matthew Newton Date: Thu, 27 Jul 2023 11:59:14 +0000 (+0100) Subject: minor documentation updates X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0e0bc21b4e4f6dae665325f5d4f99e2d58ab07ff;p=thirdparty%2Ffreeradius-server.git minor documentation updates --- diff --git a/doc/antora/main-site.yml.in b/doc/antora/main-site.yml.in index 4cacdad585d..df10d879f30 100644 --- a/doc/antora/main-site.yml.in +++ b/doc/antora/main-site.yml.in @@ -18,8 +18,8 @@ content: - 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 diff --git a/doc/antora/modules/concepts/pages/aaa.adoc b/doc/antora/modules/concepts/pages/aaa.adoc index b44ec434955..aff877ad6bb 100644 --- a/doc/antora/modules/concepts/pages/aaa.adoc +++ b/doc/antora/modules/concepts/pages/aaa.adoc @@ -6,9 +6,10 @@ There are a lot of questions about misconfigured FreeRADIUS servers 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 @@ -39,7 +40,7 @@ instructs the server to use `mschap` for authentication, too 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 diff --git a/doc/antora/modules/developers/nav.adoc b/doc/antora/modules/developers/nav.adoc index f67f5a31a29..99aaea1e107 100644 --- a/doc/antora/modules/developers/nav.adoc +++ b/doc/antora/modules/developers/nav.adoc @@ -7,4 +7,9 @@ ** 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] diff --git a/doc/antora/modules/developers/pages/bugs.adoc b/doc/antora/modules/developers/pages/bugs.adoc index fe1baed0dae..b63329c0bbe 100644 --- a/doc/antora/modules/developers/pages/bugs.adoc +++ b/doc/antora/modules/developers/pages/bugs.adoc @@ -2,22 +2,24 @@ == 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 @@ -33,7 +35,7 @@ response and much faster if you do! == 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: ``` @@ -64,7 +66,7 @@ Enable logging in `gdb` via the following commands: 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. @@ -73,7 +75,7 @@ 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: @@ -137,11 +139,11 @@ Then, do: (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 @@ -174,20 +176,19 @@ If the bug is a crash of the server, and it takes a long time for the 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 diff --git a/doc/antora/modules/developers/pages/coccinelle.adoc b/doc/antora/modules/developers/pages/coccinelle.adoc index 5f54e7ab4d1..dc06d62fa77 100644 --- a/doc/antora/modules/developers/pages/coccinelle.adoc +++ b/doc/antora/modules/developers/pages/coccinelle.adoc @@ -1,6 +1,6 @@ = 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 diff --git a/doc/antora/modules/developers/pages/coding-methods.adoc b/doc/antora/modules/developers/pages/coding-methods.adoc index a4674444e48..3de92c460eb 100644 --- a/doc/antora/modules/developers/pages/coding-methods.adoc +++ b/doc/antora/modules/developers/pages/coding-methods.adoc @@ -11,14 +11,14 @@ to write code. == 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 @@ -46,8 +46,9 @@ and you were too lazy to check for garbage input. [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 @@ -93,7 +94,7 @@ too. 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. @@ -121,10 +122,10 @@ Turn on all of the C compiler warnings possible. You might have to turn some off 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 @@ -150,7 +151,8 @@ arbitrary whitespace, and it’s easy to mess up. 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 @@ -169,7 +171,7 @@ for doing so. == 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 @@ -180,7 +182,7 @@ rejected without further review, and without comment. 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: @@ -216,11 +218,11 @@ safety, have no length limitations, no formatting limitations, and under gcc 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 diff --git a/doc/antora/modules/developers/pages/contributing.adoc b/doc/antora/modules/developers/pages/contributing.adoc index dcbe8cf0c1a..e4a4b0a1c5e 100644 --- a/doc/antora/modules/developers/pages/contributing.adoc +++ b/doc/antora/modules/developers/pages/contributing.adoc @@ -9,7 +9,7 @@ greatly increase the chances of your change being accepted. 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 @@ -23,7 +23,7 @@ things like "update file X", "bug fix for file X", or "this patch 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 diff --git a/doc/antora/modules/developers/pages/index.adoc b/doc/antora/modules/developers/pages/index.adoc index 4a864e7b407..b2bb4cb95dd 100644 --- a/doc/antora/modules/developers/pages/index.adoc +++ b/doc/antora/modules/developers/pages/index.adoc @@ -2,6 +2,9 @@ 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] @@ -10,7 +13,14 @@ List with some usual howtos for FreeRADIUS. * 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.