From de28a630e2a32711b0a9fcc192f22ebea937a651 Mon Sep 17 00:00:00 2001 From: Michael Tremer Date: Thu, 31 May 2012 22:50:46 +0000 Subject: [PATCH] Switch over to man page documentation. There are two man pages for testing how this would work and the old help texts within the shell code have been removed. --- .gitignore | 1 + Makeconfig | 22 +++++ Makefile | 16 ++-- functions.cli | 182 +++++++++--------------------------------- functions.constants | 1 + functions.firewall | 2 + man/Makefile | 45 +++++++++++ man/network-zone.8.in | 68 ++++++++++++++++ man/network.8.in | 119 +++++++++++++++++++++++++++ network | 6 +- 10 files changed, 308 insertions(+), 154 deletions(-) create mode 100644 .gitignore create mode 100644 Makeconfig create mode 100644 man/Makefile create mode 100644 man/network-zone.8.in create mode 100644 man/network.8.in diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..651ce32a --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +man/*.8 diff --git a/Makeconfig b/Makeconfig new file mode 100644 index 00000000..5c9f3315 --- /dev/null +++ b/Makeconfig @@ -0,0 +1,22 @@ +############################################################################### +# # +# IPFire.org - A linux based firewall # +# Copyright (C) 2012 IPFire Network Development Team # +# # +# This program is free software: you can redistribute it and/or modify # +# it under the terms of the GNU General Public License as published by # +# the Free Software Foundation, either version 3 of the License, or # +# (at your option) any later version. # +# # +# This program is distributed in the hope that it will be useful, # +# but WITHOUT ANY WARRANTY; without even the implied warranty of # +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # +# GNU General Public License for more details. # +# # +# You should have received a copy of the GNU General Public License # +# along with this program. If not, see . # +# # +############################################################################### + +PACKAGE_NAME = network +PACKAGE_VERSION = 003 diff --git a/Makefile b/Makefile index c8973acf..0fb47447 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,5 @@ -NAME = network -VER = 003 +include Makeconfig DESTDIR= @@ -16,9 +15,11 @@ tmpfilesdir=$(prefix)/lib/tmpfiles.d # File to store the version number in. VERSION_FILE = $(DESTDIR)$(libdir)/network/version +.PHONY: all all: - @echo "Nothing to do here." + make -C man all +.PHONY: install install: -mkdir -pv $(DESTDIR)$(sysconfdir)/{network/{ports,zones},ppp} -mkdir -pv $(DESTDIR)$(libdir)/{network,sysctl.d,udev} @@ -59,8 +60,11 @@ install: # Create the version file. : > $(VERSION_FILE) echo "# This file is automatically generated." >> $(VERSION_FILE) - echo "NETWORK_VERSION=$(VER)" >> $(VERSION_FILE) + echo "NETWORK_VERSION=$(PACKAGE_VERSION)" >> $(VERSION_FILE) + + # Descend into subdirectories. + make -C man install dist: - git archive --format tar --prefix $(NAME)-$(VER)/ HEAD | gzip -9 > \ - $(NAME)-$(VER).tar.gz + git archive --format tar --prefix $(PACKAGE_NAME)-$(PACKAGE_VERSION)/ HEAD | gzip -9 > \ + $(PACKAGE_NAME)-$(PACKAGE_VERSION).tar.gz diff --git a/functions.cli b/functions.cli index 0f6790a5..2c46bd7b 100644 --- a/functions.cli +++ b/functions.cli @@ -21,7 +21,7 @@ function cli_config() { if cli_help_requested $@; then - cli_usage root-config + cli_show_man network exit ${EXIT_OK} fi @@ -57,7 +57,7 @@ function cli_device() { device_show ${device} ;; *) - cli_usage device + cli_show_man network-device ;; esac } @@ -135,7 +135,7 @@ function cli_device_discover() { function cli_hostname() { if cli_help_requested $@; then - cli_usage hostname + cli_show_man network exit ${EXIT_OK} fi @@ -152,30 +152,9 @@ function cli_hostname() { exit ${EXIT_OK} } -function cli_hotplug() { - if cli_help_requested $@; then - cli_usage root-hotplug - exit ${EXIT_OK} - fi - - local command=${1} - shift - - case "${command}" in - device) - device_hotplug $@ - exit $? - ;; - *) - cli_usage root-hotplug - exit ${EXIT_OK} - ;; - esac -} - function cli_port() { if cli_help_requested $@; then - cli_usage root-port + cli_show_man network-port exit ${EXIT_OK} fi @@ -227,7 +206,7 @@ function cli_port() { function cli_zone() { if cli_help_requested $@; then - cli_usage root-zone + cli_show_man network-zone exit ${EXIT_OK} fi @@ -258,7 +237,7 @@ function cli_zone() { ;; *) error "Unrecognized argument: ${action}" - cli_usage root-zone-subcommands + cli_show_man network-zone exit ${EXIT_ERROR} ;; esac @@ -276,7 +255,7 @@ function cli_zone() { echo fi - cli_usage root-zone + cli_show_man network-zone exit ${EXIT_ERROR} ;; esac @@ -285,7 +264,7 @@ function cli_zone() { function cli_start() { if cli_help_requested $@; then - cli_usage root-start + cli_show_man network exit ${EXIT_OK} fi @@ -301,7 +280,7 @@ function cli_start() { function cli_stop() { if cli_help_requested $@; then - cli_usage root-stop + cli_show_man network exit ${EXIT_OK} fi @@ -317,7 +296,7 @@ function cli_stop() { function cli_restart() { if cli_help_requested $@; then - cli_usage root-restart + cli_show_man network exit ${EXIT_OK} fi @@ -331,7 +310,7 @@ function cli_restart() { function cli_status() { if cli_help_requested $@; then - cli_usage root-status + cli_show_man network exit ${EXIT_OK} fi @@ -354,7 +333,7 @@ function cli_status() { function cli_reset() { if cli_help_requested $@; then - cli_usage root-reset + cli_show_man network exit ${EXIT_OK} fi @@ -408,118 +387,6 @@ function cli_help_requested() { return ${EXIT_ERROR} } -function cli_usage() { - local what=${1} - - case "${what}" in - root) - echo "${0}: [command] " - echo - echo " start - ..." - echo " stop - ..." - echo " restart - ..." - echo " status - ..." - echo - echo " config - ..." - echo - echo " device - ..." - echo " zone - ..." - echo - ;; - root-config) - echo "${0}: ${what#root-} [KEY=VAL, ...]" - echo - echo " This command allows setting of global configuration parameters." - echo - echo " If no additional arguments are passed it will list the current configuration." - echo - echo " You can overwrite the settings like the following:" - echo - echo " ${0} ${what#root-} DEBUG=1 ..." - echo - ;; - root-reset) - echo "${0}: ${what#root-} [--force | -f]" - echo - echo " This command resets the network configuration." - echo - echo " Will delete all zones and ports." - echo - echo -e " ${COLOUR_RED}USE WITH CAUTION!${COLOUR_NORMAL}" - echo - ;; - root-start|root-stop|root-restart) - echo "${0}: ${what#root-} [--local-only|--remote-only|--all|...]" - echo - echo " This commands ${what#root-}s all zones by default." - echo " One can pass several parameters to only process a subset of all" - echo " available zones:" - echo - echo -e " ${COLOUR_BOLD}--local-only${COLOUR_NORMAL}" - echo " Process all local zones which includes every zone without red." - echo - echo -e " ${COLOUR_BOLD}--remote-only${COLOUR_NORMAL}" - echo " Process all remote zones which means only the red ones." - echo - echo -e " ${COLOUR_BOLD}--all${COLOUR_NORMAL}" - echo " Process all zones. This is the default parameter." - echo - echo " Additionally, you can pass one or more zone names which will" - echo " be processed." - echo - ;; - root-status) - echo "${0}: ${what#root-} [--local-only|--remote-only|--all|...]" - echo - echo " This commands shows status information of all zones by default." - echo " One can pass several parameters to only process a subset of all" - echo " available zones:" - echo - echo -e " ${COLOUR_BOLD}--local-only${COLOUR_NORMAL}" - echo " Process all local zones which includes every zone without red." - echo - echo -e " ${COLOUR_BOLD}--remote-only${COLOUR_NORMAL}" - echo " Process all remote zones which means only the red ones." - echo - echo -e " ${COLOUR_BOLD}--all${COLOUR_NORMAL}" - echo " Process all zones. This is the default parameter." - echo - echo " Additionally, you can pass one or more zone names which will" - echo " be processed." - echo - ;; - root-zone) - echo "${0}: ${what#root-} [ ]" - echo - echo " Create or remove a zone." - echo - echo -e " ${COLOUR_BOLD}create ${COLOUR_NORMAL}" - echo " Create a new zone of type where is an allowed" - echo " zone name." - echo - echo -e " ${COLOUR_BOLD}remove ${COLOUR_NORMAL}" - echo " Remove the zone ." - echo - echo " You may also edit the configuration of the zones." - echo - echo -e " ${COLOUR_BOLD} ...${COLOUR_NORMAL}" - echo " Edit the zone ." - echo - ;; - usage) - echo - echo " Run '${0} help' to get information how to use this tool." - echo - ;; - *) - error "No help available for this command '${what}'." - echo - ;; - esac - - echo "Network configuration tool. Report all bugs to ." -} - function cli_status_headline() { local zone=${1} @@ -557,3 +424,28 @@ function cli_get_key() { function cli_get_val() { echo "${@##*=}" } + +function cli_usage() { + local command="$@" + local basename="$(basename ${0})" + + if ! isset command; then + command="${basename} help" + fi + + echo "The given command was not understood by ${basename}." >&2 + echo "Please run '${command}' for detailed help." >&2 +} + +function cli_show_man() { + local manpage=${1} + assert isset manpage + + if ! binary_exists man; then + error "The man package is not installed on this system." + error "Please install 'man' in order to view the help." + exit ${EXIT_ERROR} + fi + + man ${manpage} +} diff --git a/functions.constants b/functions.constants index b2ff868d..6acee038 100644 --- a/functions.constants +++ b/functions.constants @@ -91,6 +91,7 @@ PORT_PATTERN_WIRELESS="wN" IPTABLES_TMPDIR= FIREWALL_CONFIG_DIR="/etc/firewall" +FIREWALL_ZONES_DIR="${FIREWALL_CONFIG_DIR}/zones" FIREWALL_CONFIG_FILE="${FIREWALL_CONFIG_DIR}/settings" FIREWALL_CONFIG_PORTFW="${FIREWALL_CONFIG_DIR}/portfw" diff --git a/functions.firewall b/functions.firewall index f8fe70af..56a840f1 100644 --- a/functions.firewall +++ b/functions.firewall @@ -155,3 +155,5 @@ function firewall_import_portfw() { esac done < ${FIREWALL_CONFIG_PORTFW} } + + diff --git a/man/Makefile b/man/Makefile new file mode 100644 index 00000000..65b1a603 --- /dev/null +++ b/man/Makefile @@ -0,0 +1,45 @@ +############################################################################### +# # +# IPFire.org - A linux based firewall # +# Copyright (C) 2012 IPFire Network Development Team # +# # +# This program is free software: you can redistribute it and/or modify # +# it under the terms of the GNU General Public License as published by # +# the Free Software Foundation, either version 3 of the License, or # +# (at your option) any later version. # +# # +# This program is distributed in the hope that it will be useful, # +# but WITHOUT ANY WARRANTY; without even the implied warranty of # +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # +# GNU General Public License for more details. # +# # +# You should have received a copy of the GNU General Public License # +# along with this program. If not, see . # +# # +############################################################################### + +include ../Makeconfig + +mandir = /usr/share/man + +MANPAGES = $(MANPAGES8) +MANPAGES_IN = $(foreach file,$(MANPAGES),$(file).in) + +MANPAGES8 = \ + network.8 \ + network-zone.8 + +.PHONY: all +all: $(MANPAGES) + @: # Do nothing. + +# Replace all placeholders. +$(MANPAGES): Makefile $(MANPAGES_IN) + sed \ + -e "s/@VERSION@/$(PACKAGE_VERSION)/g" \ + < $@.in > $@ + +.PHONY: install +install: $(MANPAGES) + -mkdir -pv $(DESTDIR)$(mandir)/man8 + cp -vf *.8 $(DESTDIR)$(mandir)/man8 diff --git a/man/network-zone.8.in b/man/network-zone.8.in new file mode 100644 index 00000000..23d2b6b6 --- /dev/null +++ b/man/network-zone.8.in @@ -0,0 +1,68 @@ +.TH network-zone 8 "1 Jun 2012" "@VERSION@" "network man page" + +.SH NAME +network-zone \- Network Configuration Control Program + +.SH SYNOPSIS +\fBnetwork [OPTIONS] zone create ...\fR +.P +\fBnetwork [OPTIONS] zone command ...\fR + +.SH DESCRIPTION +By the zone subcommands, it is very easy to configure network zones. +.PP +It is possible to create zones and remove them. Zones may also +be brought up and down and reconfigured. Their status may be viewed +as well. + +.SH OPTIONS +The \fBnetwork zone\fR command offers various commands: + +\fBcreate [options]\fR +.RS 4 +A new zone may be created by the \fBcreate\fR command. There are at least two arguments +required. +.PP +\fB\fR must be valid name for a zone which does not already exist. +\fB\fR is a valid zone hook which may require additional options. +.RE +.PP + +\fBremove \fR +.RS 4 +XXX TODO What will happen here? +.RE +.PP + +For all other commands, the name of the zone needs to be passed first: +\fBnetwork zone command\fR. + +\fB edit [OPTIONS]\fR +.RS 4 +The settings of a zone may be edited after it has been created. The options that can +be passed depend on the hook that is used for the zone. Run \fBnetwork zone edit --help\fR +to learn more about that. +.PP +It normally is required to restart/reload the zone until the new settings are taken into account. +.RE +.PP + +\fB [up|down]\fR +.RS 4 +These commands will bring the zone up/down. This is done without control of systemd, therefore +not intended to be done in a productive environment. However, these commands may be used for +debugging. +.RE +.PP + +\fB status\fR +.RS 4 +This will show some detailed information about the state if the specified zone. +.RE +.PP + +.SH SEE ALSO +network(8) + +.SH AUTHOR +Michael Tremer (michael.tremer@ipfire.org) diff --git a/man/network.8.in b/man/network.8.in new file mode 100644 index 00000000..e2c66938 --- /dev/null +++ b/man/network.8.in @@ -0,0 +1,119 @@ +.TH network 8 "31 May 2012" "@VERSION@" "network man page" + +.SH NAME +network \- Network Configuration Control Program + +.SH SYNOPSIS +\fBnetwork [--debug|-d] command\fR + +.SH DESCRIPTION +The network command is a tool which configures the network on every IPFire +system. It is a fast and versatile way to create, edit and remove +configurations, review the status of the network and it is working in the +background of the system making sure that things are running smoothly. +.PP + +.SH OPTIONS +\fB\-\-debug\fR +(short \fB\-d\fR) +.RS 4 +The \fB\-\-debug\fR switch enabled the debugging mode. In this mode, there +will be debug output in the console and written to the log files. +.PP +The debugging mode can be permanently enabled by running +\fBnetwork config DEBUG=1\fR. +.RE +.PP + +The \fBnetwork\fR command offers various commands: + +\fBstart [zone-name ...]\fR +.RS 4 +The \fBstart\fR command starts a zone. That means the network zone will be created +and brought up. +If one or more names of zones are passed to the command, only those will be started. +.PP +The startup of the zones itself is dispatches to \fBsystemd\fR(8). +.RE +.PP + +\fBstop [zone-name ...]\fR +.RS 4 +The \fBstop\fR command stops a zone. This is the inverse of the \fBstart\fR command. +.RE +.PP + +\fBrestart [zone-name ...]\fR +.RS 4 +The \fBrestart\fR command will stop and start all given zones or all. +.RE +.PP + +\fBstatus [zone-name ...]\fR +.RS 4 +The \fBstatus\fR command will show a human-readable overview of the status of the +network zones. +.RE +.PP + +\fBzone ...\fR +.RS 4 +The \fBzone\fR command is the most used command. It can configure zones. +Read more about that in \fBnetwork-zone\fR(8). +.RE +.PP + +\fBport ...\fR +.RS 4 +The \fBport\fR command is used to create, remove and configure ports. +Read more about that in \fBnetwork-port\fR(8). +.RE +.PP + +\fBdevice ...\fR +.RS 4 +The \fBdevice\fR command is used to read status information about +devices. Detailed information is to be found in \fBnetwork-device\fR(8). +.RE +.PP + +\fBconfig [KEY=VALUE ...]\fR +.RS 4 +The \fBconfig\fR command will return you are list of the global configuration +parameters of the network command. +.PP +You may set them by appending a new setting to the command line. +.RE +.PP + +\fBhostname [new-hostname]\fR +.RS 4 +The \fBhostname\fR command will return the currently configured hostname of the system. +.PP +If a new hostname is added to the command line, it will be configured, but will be set +after the next reboot. +.RE +.PP + +\fBreset\fR +.RS 4 +The \fBreset\fR command will reset all network configuration. That means all zone configurations +will be removed and there will be no networking at the next reboot. +.RE +.PP + +.SH EXIT CODES +The \fBnetwork\fR command will normally exit with code 0. If there has been a problem +and the requested action could not be done, the exit code is unequal to zero. + +.SH BUGS +Please report all bugs to the official bugtracker at http://bugs.ipfire.org/. + +.SH SEE ALSO +network-config(8), +network-device(8), +network-port(8), +network-zone(8) + +.SH AUTHOR +Michael Tremer (michael.tremer@ipfire.org) diff --git a/network b/network index a3b08c6d..16eb0874 100755 --- a/network +++ b/network @@ -41,18 +41,18 @@ case "${action}" in init_run ;; - config|hostname|hotplug|port|device|zone|start|stop|restart|status|reset) + config|hostname|port|device|zone|start|stop|restart|status|reset) cli_${action} $@ ;; ""|help|--help|-h) - cli_usage root + cli_show_man network exit ${EXIT_OK} ;; *) error "Invalid command given: ${action}" - cli_usage usage + cli_usage "network help" exit ${EXIT_CONF_ERROR} ;; esac -- 2.39.2