From: Michael Tremer Date: Sun, 21 Jun 2009 16:55:09 +0000 (+0200) Subject: Added some documentation to the network tools. X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e68e56b5fa637c2f92ecc3ccb01c5a8332705f2b;p=ipfire-3.x.git Added some documentation to the network tools. --- diff --git a/src/network/lib/functions b/src/network/lib/functions index dca54d5f3..445b7642f 100644 --- a/src/network/lib/functions +++ b/src/network/lib/functions @@ -19,7 +19,7 @@ # # ############################################################################### -HOME_DIR=/lib/network +HOME_DIR=${HOME_DIR-/lib/network} CONFIG_DIR=/etc/sysconfig/networking HOOKS_DIR=${HOME_DIR}/hooks diff --git a/src/network/lib/hooks/README b/src/network/lib/hooks/README new file mode 100644 index 000000000..09ca2307a --- /dev/null +++ b/src/network/lib/hooks/README @@ -0,0 +1,86 @@ +HOOKS README + +A hook is file that can configure a specific network connection (e.g. ethernet) +or protocol (e.g. ipv4-static). + +They are expandable and standalone. Means, when you call a file, you will +run it and pass some options and an action to it. + + /lib/network/hooks/HOOOK [options] [options to action] + +There are two types of hooks: + zone + These hooks applies to a zone and does configuration on it. + Mainly, it configures the IP protocol or something else. + + port + These hooks add ports to zones. + +DEFINES: + So, to know what type of hook this is, we have to define some variables + in the header of the file. + + HOOK_NAME + The name of the hook. This is normally the file name. + + HOOK_TYPE + zone or port. See section above. + + +INLCUDES: + These files get included in the header. + + /lib/lsb/init-functions + For pretty messages + + /lib/network/functions + Our networking funktions. + + +OPTIONS: + Options have at least to be for zone file: + + --config=CONFIG + Includes the given config file CONFIG. + If there is an error when loading the config file or the parameters are + wrong or invalid, the script will pass an error with code ${EXIT_CONF_ERROR}! + + --port=PORT + Takes a port (either as device (eth0) or as mac (00:11:22:33:44:55)). + + --zone=ZONE + Takes the name of a zone. + + +ACTION: + Actions that always have to be defined: + help + Gives the user a short help how to use the command and its arguments. + + info + Gives some information about the hook (mainly for internal use of the scripts). + See below. + + status + Gives information if the hook is active or not. + + config + This is the command that creates the configuration for each hook. + It will accept some more arguments in the command line + and return either ${EXIT_OK} or ${EXIT_ERROR}. + + Actions that have to be defined for a zone hook: + pre-up + This gets runned before the zone gets up. + + pre-down. + This is runned before the zone is set down. + + post-up + After setting up the zone, this command will be executed. + + post-down + After the zone has vanished, this part of the script is called. + + All these actions will return ${EXIT_OK} when everything went fine. + If not, they will return ${EXIT_ERROR}. diff --git a/src/network/lib/hooks/ethernet b/src/network/lib/hooks/ethernet index d90812c9d..83c390f8e 100755 --- a/src/network/lib/hooks/ethernet +++ b/src/network/lib/hooks/ethernet @@ -85,6 +85,33 @@ done case "${action}" in help) + echo -e "${BOLD}Hook (${HOOK_NAME}) help:" + echo + echo -e " ${BOLD}Summary:${NORMAL}" + echo " The ethernet-hook controls connection via ethernet." + echo " You will need this to access your local lan." + echo + echo -e " ${BOLD}Usage:${NORMAL}" + #echo " --config=" + #echo " Includes a config file." + #echo " Example: --config=/etc/sysconfig/network/green0/port-00:11:22:33:44:55" + #echo " --port=" + #echo " Passes the port to the script." + #echo " Example: --port=black0 or --port=00:11:22:33:44:55" + #echo " --zone=" + #echo " Passes the zone to the script." + #echo " Example: --zone=green0" + #echo + #echo -e " ${BOLD}Commands:${NORMAL}" + #echo + echo " This hook only needs the name of the network device" + echo " that should be attached to the zone." + echo " The device identifier can either be a mac address or" + echo " a device name." + echo + echo " Example: network zone addport green0 ethernet black0" + echo " network zone addport green0 ethernet 00:11:22:33:44:55" + echo ;; info) diff --git a/src/network/network b/src/network/network index 93bd0c089..d60056f42 100644 --- a/src/network/network +++ b/src/network/network @@ -26,6 +26,7 @@ ERROR="\\033[1;31m" if [ -e "/lib/network/functions" ]; then . /lib/network/functions elif [ -e "lib/functions" ]; then + HOME_DIR="lib" . lib/functions else echo "Cannot find functions library. Exiting." >&2 @@ -37,12 +38,14 @@ function usage() { case "$1" in main|"") echo "This script will help you configuring your network." - echo "You should know that there are two different things:" echo + echo "You should know that there are three different things:" + echo + echo " hook: A script to control connections and protocols." + echo " port: A physical connection to somewhere." echo " zone: A group of ports." - echo " port: Connection to somewhere." echo - echo " $0 [global flags] ... or" + echo " $0 [global flags] ... or" echo " $0 [global flags] " echo echo -e "${BOLD}Global flags:${NORMAL}" @@ -56,12 +59,29 @@ function usage() { echo " restart - Restarts the whole network." echo " reload - Reloads the whole network." echo - echo " zone - Run \"$0 zone help\" for more information." + echo " hook - Run \"$0 hook help\" for more information." echo " port - Run \"$0 port help\" for more information." + echo " zone - Run \"$0 zone help\" for more information." echo ;; - hook) - echo "TODO" + hook*) + echo -e "${BOLD}Hook configuration:${NORMAL}" + echo + echo " ${0} [global options] hook " + echo + echo -e "${BOLD}1st level commands:${NORMAL}" + echo -e " ${BOLD}list:${NORMAL}" + echo " Returns a list of all available hooks." + echo + echo + echo " ${0} [global options] hook " + echo + echo -e "${BOLD}2nd level commands:${NORMAL}" + echo -e " ${BOLD}help:${NORMAL}" + echo " Displays some help about the given hook." + echo + echo " Example: $0 hook ethernet help" + echo ;; port) echo -e "${BOLD}Port Configuration:${NORMAL}" @@ -399,13 +419,25 @@ while [ "$#" -gt 0 ]; do _exit $? ;; hook|hooks) - arg=$1 + case "$1" in + list) + for i in ${HOOKS_DIR}/*; do + hook_exists ${i##*/} && echo ${i} + done + _exit $? + ;; + *) + if hook_exists ${1}; then + hook=${1} + else + usage hook + fi + esac shift - case "$arg" in + case "$1" in help|info) - hook=$1 if hook_exists ${hook}; then - hook_run ${hook} ${arg} + hook_run ${hook} ${1} _exit $? else error "Hook ${hook} does not exist or is not executeable."