From: Alan T. DeKok Date: Mon, 21 Dec 2020 22:15:08 +0000 (-0500) Subject: move "man" pages to antora X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=8df42ca428120d7d6e6a0b6c4abb25607ea5c38e;p=thirdparty%2Ffreeradius-server.git move "man" pages to antora and add rules to build / install the "man" pages --- diff --git a/doc/all.mk b/doc/all.mk index 0bfdcd74ac6..33c703a4a5a 100644 --- a/doc/all.mk +++ b/doc/all.mk @@ -6,7 +6,7 @@ # to fix that. So, only run those shell scripts if we're going to # build the documentation. # -WITH_DOC := $(strip $(foreach x,doc html pdf doxygen,$(findstring $(x),$(MAKECMDGOALS)))) +WITH_DOC := $(strip $(foreach x,doc html man pdf doxygen,$(findstring $(x),$(MAKECMDGOALS)))) ifneq "$(WITH_DOC)" "" # @@ -102,21 +102,20 @@ $(foreach FILE,$(ALL_DOC_FILES),$(eval $(call ADD_INSTALL_RULE.file,doc/${FILE}, # install.doc: $(addprefix $(R)/$(docdir)/,$(ALL_DOC_FILES)) -# -# For now, list each "man" page individually. They are all generated from source -# "adoc" files. And "make" isn't smart enough to figure that out. -# -# We install doc/man/foo.? into $(R)/$(mandir)/man?/foo.? -# -# Because GNU Make sucks at string substitution, we have stupid rules to do that. # # Not all of the "man" files have been converted to asciidoc, so we have a "install.doc.man" # rule here, instead of overloading the "install.man" rule. # -MAN_FILES := doc/man/radclient.1 doc/man/radiusd.8 -INSTALL_MAN_FILES := $(join $(patsubst .%,$(R)/$(mandir)/man%/,$(suffix $(MAN_FILES))),$(patsubst doc/man/%,%,$(MAN_FILES))) - -$(foreach FILE,$(MAN_FILES),$(eval $(call ADD_INSTALL_RULE.file,${FILE},$(R)/$(mandir)/$(join $(patsubst .%,man%/,$(suffix ${FILE})),$(patsubst doc/man/%,%,${FILE}))))) +ADOC2MAN_FILES := $(filter-out %/index.adoc,$(wildcard doc/antora/modules/reference/pages/man/*.adoc)) +$(BUILD_DIR)/make/man.mk: $(ADOC2MAN_FILES) | $(BUILD_DIR)/make + @rm -f $@ + for x in $^; do \ + y=$$(grep :manvolnum: $$x | awk '{print $$2}'); \ + echo "INSTALL_MAN_FILES += $(R)/$(mandir)/man$$y/$$(basename $$x | sed 's/.adoc//' ).$$y" >> $@; \ + echo "$(R)/$(mandir)/man$$y/$$(basename $$x | sed 's/.adoc//' ).$$y: $$x | $(R)/$(mandir)/man$$y" >> $@; \ + echo "\t"'asciidoctor -b manpage $$< > $$@' >> $@; \ + echo "" >> $@; \ + done install.doc.man: $(INSTALL_MAN_FILES) diff --git a/doc/antora/modules/reference/nav.adoc b/doc/antora/modules/reference/nav.adoc index b5b5e4a1bad..3aa5b30032c 100644 --- a/doc/antora/modules/reference/nav.adoc +++ b/doc/antora/modules/reference/nav.adoc @@ -58,3 +58,9 @@ *** xref:xlat/character.adoc[Single Letter Expansions] *** xref:xlat/attribute.adoc[Attribute References] *** xref:xlat/module.adoc[Module References] + +** xref:man/index.adoc["man" pages] +*** xref:man/radclient.adoc[radclient] +*** xref:man/radiusd.adoc[radiusd] +*** xref:man/radmin.adoc[radmin] +*** xref:man/radsniff.adoc[radsniff] diff --git a/doc/antora/modules/reference/pages/man/index.adoc b/doc/antora/modules/reference/pages/man/index.adoc new file mode 100644 index 00000000000..9f27cc52dd8 --- /dev/null +++ b/doc/antora/modules/reference/pages/man/index.adoc @@ -0,0 +1,9 @@ += Man pages + +The xref:man/radclient.adoc[radclient] program. + +The main xref:man/radiusd.adoc[radiusd] daemon. + +The command-line tool for radiusd, xref:man/radmin.adoc[radmin]. + +A RADIUS-aware packet capture tool, xref:man/radsniff.adoc[radsniff]. diff --git a/doc/antora/modules/man/pages/radclient.adoc b/doc/antora/modules/reference/pages/man/radclient.adoc similarity index 99% rename from doc/antora/modules/man/pages/radclient.adoc rename to doc/antora/modules/reference/pages/man/radclient.adoc index 1852e7ae829..237e9c2a66f 100644 --- a/doc/antora/modules/man/pages/radclient.adoc +++ b/doc/antora/modules/reference/pages/man/radclient.adoc @@ -5,6 +5,7 @@ Alan DeKok :man manual: FreeRADIUS :man source: FreeRADIUS :page-layout: base +:manvolnum: 1 == NAME diff --git a/doc/antora/modules/man/pages/radiusd.adoc b/doc/antora/modules/reference/pages/man/radiusd.adoc similarity index 99% rename from doc/antora/modules/man/pages/radiusd.adoc rename to doc/antora/modules/reference/pages/man/radiusd.adoc index 30a96ab235c..0f8c6ed644c 100644 --- a/doc/antora/modules/man/pages/radiusd.adoc +++ b/doc/antora/modules/reference/pages/man/radiusd.adoc @@ -5,7 +5,7 @@ Alan DeKok :man manual: FreeRADIUS :man source: FreeRADIUS :page-layout: base - +:manvolnum: 8 == NAME diff --git a/doc/antora/modules/reference/pages/man/radmin.adoc b/doc/antora/modules/reference/pages/man/radmin.adoc new file mode 100644 index 00000000000..14fb20c34e1 --- /dev/null +++ b/doc/antora/modules/reference/pages/man/radmin.adoc @@ -0,0 +1,145 @@ += radmin(8) +Alan DeKok +:doctype: manpage +:release-version: 4.0.0 +:man manual: FreeRADIUS +:man source: FreeRADIUS +:page-layout: base +:manvolnum: 8 + +== NAME + +radmin - FreeRADIUS Administration tool + +== SYNOPSIS + +*radmin* [*-d* _config_directory_] [*-e* _command_] [*-E*] [*-f* +_socket_file_] [*-h*] [*-i* _input_file_] [*-l* _log_file_] [*-n* +_name_] [*-q*] + +== DESCRIPTION + +FreeRADIUS Server administration tool that connects to the control +socket of a running server, and gives a command-line interface to it. + +At this time, only a few commands are supported. Please type "help" at +the command prompt for detailed information about the supported +commands. + +== WARNING + +The security protections offered by this command are limited to the +permissions on the Unix domain socket, and the server configuration. If +someone can connect to the Unix domain socket, they have a substantial +amount of control over the server. + +== OPTIONS + +The following command-line options are accepted by the program. + +* Defaults to _/etc/raddb_. *radmin* looks here for the server +configuration files to find the "listen" section that defines the +control socket filename. +* Run _command_ and exit. +* Echo commands as they are being executed. +* Specify the socket filename directly. The radiusd.conf file is not +read. +* Print usage help information. +* Reads input from the specified file. If not specified, stdin is used. +This also sets "-q". +* Writes the commands which are executed to this log file. This +functionality is off by default. +* Read _raddb/name.conf_ instead of _raddb/radiusd.conf_. +* Quiet mode. + +== COMMANDS + +The commands implemented by the command-line interface are almost +completely controlled by the server. There are a few commands +interpreted locally by radmin: + +* Reconnect to the server. +* Exit from radmin. +* Exit from radmin. + +The other commands are implemented by the server. Type "help" at the +prompt for more information. + +== EXAMPLES + +* Set debug logs to /var/log/radius/bob.log. There is very little +checking of this filename. Rogue administrators may be able use this +command to over-write almost any file on the system. If those +administrators have write access to "radius.conf", they can do the same +thing without radmin, too. +* Enable debugging output for all requests that match the condition. Any +"unlang" condition is valid here. The condition is parsed as a string, +so it must be enclosed in single or double quotes. Strings enclosed in +double-quotes must have back-slashes and the quotation marks escaped +inside of the string. + +Only one debug condition can be active at a time. + +* A more complex condition that enables debugging output for requests +containing User-Name "bob", or requests that originate from source IP +address 192.0.2.22. +* Disable debug conditionals. + +== FULL LIST OF COMMANDS + +* do sub-command of add +* Add client configuration commands +* Add new client definition from +* debugging commands +* Enable debugging for requests matching [condition] +* Set debug level to . Higher is more debugging. +* Send all debugging output to [filename] +* do sub-command of del +* Delete client configuration commands +* Delete a dynamically created client +* sends a HUP signal to the server, or optionally to one module +* commands to inject packets into a running server +* Inject packets to the destination IP and port. +* Inject packets as if they came from +* Inject packet from input-file>, with results sent to +* reconnect to a running server +* terminates the server, and cause it to exit +* do sub-command of set +* set module commands +* set configuration for +* set the module to be alive or dead (always return "fail") +* set home server commands +* set state for given home server +* do sub-command of show +* do sub-command of client +* show configuration for given client +* shows list of global clients +* show debug properties +* Shows current debugging condition. +* Shows current debugging level. +* Shows current debugging file. +* do sub-command of home_server +* show configuration for given home server +* shows list of home servers +* shows state of given home server +* do sub-command of module +* show configuration for given module +* show other module properties +* shows list of loaded modules +* show sections where may be used +* shows time at which server started +* Prints version of the running server +* Prints out configuration as XML +* do sub-command of stats +* show statistics for given client, or for all clients (auth or acct) +* show statistics for given home server (ipaddr and port), or for all +home servers (auth or acct) +* show statistics for the given detail file + +== SEE ALSO + +unlang(5), radiusd.conf(5), raddb/sites-available/control-socket + +== AUTHOR + +Alan DeKok diff --git a/doc/antora/modules/man/pages/radsniff.adoc b/doc/antora/modules/reference/pages/man/radsniff.adoc similarity index 99% rename from doc/antora/modules/man/pages/radsniff.adoc rename to doc/antora/modules/reference/pages/man/radsniff.adoc index 02dbfc29c1b..83ec3645575 100644 --- a/doc/antora/modules/man/pages/radsniff.adoc +++ b/doc/antora/modules/reference/pages/man/radsniff.adoc @@ -5,6 +5,7 @@ Alan DeKok :man manual: FreeRADIUS :man source: FreeRADIUS :page-layout: base +:manvolnum: 8 == NAME diff --git a/man/man8/radmin.8 b/man/man8/radmin.8 deleted file mode 100644 index 8e11eadd5fb..00000000000 --- a/man/man8/radmin.8 +++ /dev/null @@ -1,189 +0,0 @@ -.TH RADMIN 8 "03 Feb 2015" "" "FreeRADIUS Server Administration Tool" -.SH NAME -radmin - FreeRADIUS Administration tool -.SH SYNOPSIS -.B radmin -.RB [ \-d -.IR config_directory ] -.RB [ \-e -.IR command ] -.RB [ \-E ] -.RB [ \-f -.IR socket_file ] -.RB [ \-h ] -.RB [ \-i -.IR input_file ] -.RB [ \-l -.IR log_file ] -.RB [ \-n -.IR name ] -.RB [ \-q ] -.SH DESCRIPTION -FreeRADIUS Server administration tool that connects to the control -socket of a running server, and gives a command-line interface to it. - -At this time, only a few commands are supported. Please type "help" -at the command prompt for detailed information about the supported -commands. -.SH WARNING -The security protections offered by this command are limited to the -permissions on the Unix domain socket, and the server -configuration. If someone can connect to the Unix domain socket, they -have a substantial amount of control over the server. -.SH OPTIONS -The following command-line options are accepted by the program. -.IP "\-d \fIconfig directory\fP" -Defaults to \fI/etc/raddb\fP. \fBradmin\fP looks here for the server -configuration files to find the "listen" section that defines the -control socket filename. -.IP "\-e \fIcommand\fP" -Run \fIcommand\fP and exit. -.IP \-E -Echo commands as they are being executed. -.IP "\-f \fIsocket_file\fP" -Specify the socket filename directly. The radiusd.conf file is not read. -.IP \-h -Print usage help information. -.IP "\-i \fIinput_file\fP" -Reads input from the specified file. If not specified, stdin is used. -This also sets "-q". -.IP "\-l \fIlog_file\fP" -Writes the commands which are executed to this log file. This -functionality is off by default. -.IP "\-n \fImname\fP" -Read \fIraddb/name.conf\fP instead of \fIraddb/radiusd.conf\fP. -.IP \-q -Quiet mode. -.SH COMMANDS -The commands implemented by the command-line interface are almost -completely controlled by the server. There are a few commands -interpreted locally by radmin: -.IP reconnect -Reconnect to the server. -.IP quit -Exit from radmin. -.IP exit -Exit from radmin. -.PP -The other commands are implemented by the server. Type "help" at the -prompt for more information. -.SH EXAMPLES -.IP debug\ file\ /var/log/radius/bob.log -Set debug logs to /var/log/radius/bob.log. There is very little -checking of this filename. Rogue administrators may be able use this -command to over-write almost any file on the system. If those -administrators have write access to "radius.conf", they can do the -same thing without radmin, too. -.IP debug\ condition\ '(User-Name\ ==\ "bob")' -Enable debugging output for all requests that match the condition. -Any "unlang" condition is valid here. The condition is parsed as a -string, so it must be enclosed in single or double quotes. Strings -enclosed in double-quotes must have back-slashes and the quotation -marks escaped inside of the string. - -Only one debug condition can be active at a time. -.IP "debug condition '((User-Name == ""bob"") || (Packet-Src-IP-Address == 192.0.2.22))'" -A more complex condition that enables debugging output for requests -containing User-Name "bob", or requests that originate from source IP -address 192.0.2.22. -.IP debug\ condition -Disable debug conditionals. -.SH FULL LIST OF COMMANDS -.IP add\ -do sub-command of add -.IP add\ client\ -Add client configuration commands -.IP add\ client\ file\ -Add new client definition from -.IP debug\ -debugging commands -.IP debug\ condition\ [condition] -Enable debugging for requests matching [condition] -.IP debug\ level\ -Set debug level to . Higher is more debugging. -.IP debug\ file\ [filename] -Send all debugging output to [filename] -.IP del\ -do sub-command of del -.IP del\ client\ -Delete client configuration commands -.IP del\ client\ ipaddr\ -Delete a dynamically created client -.IP hup\ [module] -sends a HUP signal to the server, or optionally to one module -.IP inject\ -commands to inject packets into a running server -.IP inject\ to\ \ -Inject packets to the destination IP and port. -.IP inject\ from\ -Inject packets as if they came from -.IP inject\ file\ \ -Inject packet from input-file>, with results sent to -.IP reconnect -reconnect to a running server -.IP terminate -terminates the server, and cause it to exit -.IP set\ -do sub-command of set -.IP set\ module\ -set module commands -.IP set\ module\ config\ \ variable\ value -set configuration for -.IP set\ module\ status\ [alive|dead] -set the module to be alive or dead (always return "fail") -.IP set\ home_server\ -set home server commands -.IP set\ home_server\ state\ \ \ [alive|dead] -set state for given home server -.IP show\ -do sub-command of show -.IP show\ client\ -do sub-command of client -.IP show\ client\ config\ -show configuration for given client -.IP show\ client\ list -shows list of global clients -.IP show\ debug\ -show debug properties -.IP show\ debug\ condition -Shows current debugging condition. -.IP show\ debug\ level -Shows current debugging level. -.IP show\ debug\ file -Shows current debugging file. -.IP show\ home_server\ -do sub-command of home_server -.IP show\ home_server\ config\ \ -show configuration for given home server -.IP show\ home_server\ list -shows list of home servers -.IP show\ home_server\ state\ \ -shows state of given home server -.IP show\ module\ -do sub-command of module -.IP show\ module\ config\ -show configuration for given module -.IP show\ module\ flags\ -show other module properties -.IP show\ module\ list -shows list of loaded modules -.IP show\ module\ methods\ -show sections where may be used -.IP show\ uptime -shows time at which server started -.IP show\ version -Prints version of the running server -.IP show\ xml\ -Prints out configuration as XML -.IP stats\ -do sub-command of stats -.IP stats\ client\ [auth/acct]\ -show statistics for given client, or for all clients (auth or acct) -.IP stats\ home_server\ [/auth/acct]\ -show statistics for given home server (ipaddr and port), or for all home servers (auth or acct) -.IP stats\ detail\ -show statistics for the given detail file -.SH SEE ALSO -unlang(5), radiusd.conf(5), raddb/sites-available/control-socket -.SH AUTHOR -Alan DeKok