For details see cfg2html.html
@(#) $Header: /home/cvs/cfg2html_cvs/cfg2html_git/linux/README,v 6.18 2023/10/16 06:36:52 ralph Exp $


This is the READ ME for (the old) cfg2html-linux version 7.xx (c) by ROSE SWE, Dipl.-Ing. Ralph Roth

!! WARNING, USE the cfg2html-linux script AT YOUR OWN RISK !!
-------------------------------------------------------------


This text should be formatted in DOS/Windows CR/LF format so that it can be sent
(and read) by Windows mail programs!

This is the "Swiss Army Knife" for the Account Support Engineer, Customer
Engineer, Sysadmin etc. I wrote it to get the necessary information to plan an
update, do basic troubleshooting or performance analysis. As a bonus, cfg2html
produces nice HTML and plain ASCII documentation. If you miss something, let me
know!

cfg2html is a UNIX shell script similar to check_config or get_config, except
that it produces HTML (and plain ASCII) system documentation for HP-UX
10.xx/11.xx, SCO-UNIX, AIX, Sun OS and Linux systems. Plugins for SAP, Oracle,
Informix, MC/ServiceGuard, FibreChannel, TIP/ix, Mass Storage, Network Node
Manager and DataProtector etc. are included.


 ___           _        _ _       _   _
|_ _|_ __  ___| |_ __ _| | | __ _| |_(_) ___  _ __
 | || '_ \/ __| __/ _` | | |/ _` | __| |/ _ \| '_ \
 | || | | \__ \ || (_| | | | (_| | |_| | (_) | | | |
|___|_| |_|___/\__\__,_|_|_|\__,_|\__|_|\___/|_| |_|
---------------------------------------------------------------------------

To install and to execute cfg2html you must be root! A normal user account will
not work!

tar ball: To install the script, edit the Makefile and type make install. If you
use the packages, read the man pages for dpkg or rpm to install.

On SLES/openSUSE

   # zypper in cfg2html_linux-7*.rpm

On CentOS8/RHEL

   [ralph@ralph2co ~]$ sudo rpm -hiv cfg2html-6.41.1.16.gedc280d-1.git202011230748.noarch.rpm
   error: Failed dependencies:
      psmisc is needed by cfg2html-6.41.1.16.gedc280d-1.git202011230748.noarch

So better use yum to resolve dependencies:
   [ralph@ralph2co ~]$ sudo yum install cfg2html-6.41.1.16.gedc280d-1.git202011230748.noarch.rpm


On the other RPM boxes where cfg2html is already installed do this:

   # rpm -hiv cfg2html-linux-6.24-7.noarch.rpm
   Preparing...                ########################################### [100%]
         file /usr/bin/cfg2html-linux from install of cfg2html-linux-6.24-7 conflicts with file from package cfg2html-linux-6.23-11
         file /usr/share/man/man8/cfg2html-linux.8.gz from install of cfg2html-linux-6.24-7 conflicts with file from package cfg2html-linux-6.23-11
   # rpm -hiv --freshen cfg2html-linux-6.24-7.noarch.rpm
   Preparing...                ########################################### [100%]
      1:cfg2html-linux         ########################################### [100%]

   hklinx01:~/cfg> sudo rpm -hiv cfg2html-linux-6.74-1.noarch.rpm
   Password:
   Preparing...                ########################################### [100%]
         file /etc/cfg2html/plugins from install of cfg2html-linux-6.74-1 conflicts with file from package cfg2html-linux-6.61-2
         file /usr/bin/cfg2html from install of cfg2html-linux-6.74-1 conflicts with file from package cfg2html-linux-6.61-2
         file /usr/bin/cfg2html-linux from install of cfg2html-linux-6.74-1 conflicts with file from package cfg2html-linux-6.61-2
         file /usr/share/man/man8/cfg2html-linux.8.gz from install of cfg2html-linux-6.74-1 conflicts with file from package cfg2html-linux-6.61-2


 ____       _       _     _
|  _ \ __ _| |_ ___| |__ (_)_ __   __ _
| |_) / _` | __/ __| '_ \| | '_ \ / _` |
|  __/ (_| | || (__| | | | | | | | (_| |
|_|   \__,_|\__\___|_| |_|_|_| |_|\__, |
                                  |___/
------------------------------------------------------------------
Read this if you are a developer and interested in enhancing cfg2html!

OK, I fixed a bug and enhanced cfg2html, how do I make a diff for upstream
enhancement?

That is quite easy. First, get yourself GNU diff. The other diffs will work, too,
but this tutorial only applies to GNU diff. We want unified diffs!

   1. If you change cfg2html-linux, please mark your changes with for example
      # <name>. Do not forgot to remove all backup files from your editor.
   2. Rename the directory with your new, patched cfg2html-linux-x.xx to, say,
      cfg2html-linux-x.xx.patched
   3. Unpack the original distribution tar ball.
   4. Now type:

      cd cfg2html-linux-x.xx.patched
      make clean
      cd ..
      diff -uNr cfg2html-linux-x.xx cfg2html-linux-x.xx.patched | gzip -c \
       > cfg2html-linux-x.xx.diff.gz

      This is for GNU diff. You vendor's diff may not know the -u option, in
      which case you should try -c instead.
   5. Now send the compressed diff to my email address:
      cfg2hthml@hotmail.com (subject [cfg2html] + your text)


The "-u" creates a unified diff, which has 3 lines of context per default. This
has the advantage that patches can be applied to other versions of
cfg2html-linux, too.

The "-N" treats new files as empty. That means if you add a file, diff will put
it in the diff, too. This has the advantage that your file is not lost. It has
the disadvantage that "Makefile" and so on are put into the diff, too. So for
patches where you don't add new files, you can omit the "-N".

The "-r" means recursive. For cfg2html-linux this is only important if you change
stuff in sub directories. But it is good habit to use it.

------------------------------------------------------------------------------

How to apply the Patches/Diffs?

  $ gunzip delta-1-14-3rar.gz
  $ patch -p0 < delta-1-14-3rar        ## --dry-run
  patching file cfg2html-linux-1.14/cfg2html-linux
  patching file cfg2html-linux-1.14/cfg2html_urls.html

 _____      _                 _
| ____|_  _| |_ ___ _ __  ___(_) ___  _ __  ___
|  _| \ \/ / __/ _ \ '_ \/ __| |/ _ \| '_ \/ __|
| |___ >  <| ||  __/ | | \__ \ | (_) | | | \__ \
|_____/_/\_\\__\___|_| |_|___/_|\___/|_| |_|___/
---------------------------------------------------------------------------

Extending `cfg2html` is a straightforward process accomplished by crafting small
scripts and configuring them as plugins as defined in the `/etc/cfg2html/plugins`
file. The possibilities within your plugin are virtually limitless, with the
entire stdout content being incorporated into the output file.

WARNING: be particularly careful to ensure that only root can write to /etc/cfg2html/plugins
along with the other plugin directories and files
as each configured script will be run as root when cfg2html is run when Plugins are enabled (-P).

To ensure seamless integration of your script as a `cfg2html` plugin, adhere to
the following two essential guidelines, A and B.  The following assumes the
cfg2html script resides within /usr/local/src/cfg2html.

A: In the /etc/cfg2html/plugins file, define the following 2 variables (examples shown):

CFG2HTML_PLUGIN_DIR=/usr/local/src/cfg2html/linux/contrib/plugins  # The location of the plugins' repository
CFG2HTML_PLUGINS="bdf"                            # a space-separated list of plugin scripts to run, or "all"

B: Create each plugin script file specified in $CFG2HTML_PLUGINS in directory $CFG2HTML_PLUGIN_DIR.
You can use the /usr/local/src/cfg2html/linux/contrib/plugins/templateplugin file as a model:

1. Define your desired paragraph title by assigning it to a variable named `CFG2HTML_PLUGINTITLE`.
2. Execute all of your program's logic within a function aptly named "cfg2html_plugin."

For reference and inspiration, you can explore a wealth of sample `cfg2html`
plugins available in the `contrib/plugins/` directory within the `cfg2html`
distribution.

Please note that contrib scripts are additional programs provided as "bonuses"
and are not directly used or executed by `cfg2html` itself.

 ____                       _ _
/ ___|  ___  ___ _   _ _ __(_) |_ _   _
\___ \ / _ \/ __| | | | '__| | __| | | |
 ___) |  __/ (__| |_| | |  | | |_| |_| |
|____/ \___|\___|\__,_|_|  |_|\__|\__, |
                                  |___/
---------------------------------------------------------------------------

For security reasons it is better to store the HTML and ASCII files in a safe
place where only root user have access. Then remove the files from your file
system.

  Usage: cfg2html_linux [OPTION]
  creates HTML and plain ASCII host documentation

  -o            set directory to write or use the environment
                variable OUTDIR="/path/to/dir" (directory must
                exist
  -v            output version information and exit
  -h            display this help and exit

  use the following options to disable collections:

  -s            disable: System
  -c            disable: Cron
  -S            disable: Software
  -f            disable: Filesystem
  -l            disable: LVM
  -k            disable: Kernel
  -e            disable: Enhancements
  -n            disable: Network
  -a            disable: Applications
  -H            disable: Hardware
  -x            don't create background images


 ___         _          _  __   __          _
| _ \___ _ _| |_ ___ __| | \ \ / /__ _ _ __(_)___ _ _  ___
|  _/ _ \ '_|  _/ -_) _` |  \ V / -_) '_(_-< / _ \ ' \(_-<
|_| \___/_|  \__\___\__,_|   \_/\___|_| /__/_\___/_||_/__/
------------------------------------------------------------------

For your information, there are also ported *NIX versions available on the web
page for free downloading!

Maintainer of the different versions

HP-UX            : Ralph Roth
                   Contributors: Thomas Brix, Martin Kalmbach

Linux port       : Michael Meifert
                   Contributors: Michael Meier,
                   Linux (debian/hppa): Ralph Roth

                   To check the rpm use:
                           rpm -qpl cfg2html-linux-6.16-2.noarch.rpm
                   To check the deb use:
                           dpkg -c cfg2html-linux_6.16-2_all.deb

Sun Solaris port : Trond Eirik Aune [teaune@online.no]
                   Testing: Gert.Leerdam@getronics.com
                   Version 1.7++: Van Laethem, Marc (hp)

SCO port         : Jan Damen, Support Specialist, jdamen@triple-p.nl

AIX port         : Gert Leerdam, Gert.Leerdam@getronics.com

Win32            : Better use GetConfig:  www.getconfig.com


 _   _               ____   ____            _             _
| | | | _____      _|___ \ / ___|___  _ __ | |_ __ _  ___| |_
| |_| |/ _ \ \ /\ / / __) | |   / _ \| '_ \| __/ _` |/ __| __|
|  _  | (_) \ V  V / / __/| |__| (_) | | | | || (_| | (__| |_
|_| |_|\___/ \_/\_/ |_____|\____\___/|_| |_|\__\__,_|\___|\__|
------------------------------------------------------------------

You can contact me (Ralph Roth) the following ways

1.) Instant Messenger   (deprecated)
2.) Email

1.) I have the following accounts:

ICQ:          22 11 20 58   (rose_swe)
Yahoo:        rose_swe

-------------------------------------------------------------------

2.) Email: I do spam filtering with various tools, so put only me in the "To:"
field, not in the "CC:" or "BCC:" field! No Subjects and text that could be flag
by a rule based or fuzzy logic spam filter!

The email address is             cfg2html@hotmail.com
Subject must begin with    [cfg2html]


 _____ _    ___      ____  __ _
|  ___/ \  / _ \    / /  \/  (_)___  ___
| |_ / _ \| | | |  / /| |\/| | / __|/ __|
|  _/ ___ \ |_| | / / | |  | | \__ \ (__
|_|/_/   \_\__\_\/_/  |_|  |_|_|___/\___|
---------------------------------------------------------------------------

Known Problems
--------------

Executing cfg2html
------------------

1.) If Firestarter is running, you may get long timeouts on the command iptables --list.
2.) what (1) is missing - please install the what command
3.) cfg2html-linux depends on bash. Don't execute cfg2html with sh ./cfg2html-linux

If cfg2html hangs
-----------------

To get the first impression where cfg2html hangs, change to the /tmp directory
and issue an "ls -ltr". Depending on your hostname(1) you should see some files
beginning with your hostname, e.g.:

-rw-r--r--   1 root       sys           6713 Apr 28 10:37 test_neu.html
-rw-r--r--   1 root       sys           1343 Apr 28 10:37 test_neu.txt
-rw-r--r--   1 root       sys         761532 Apr 28 10:37 test_neu.txt.13320
-rw-r--r--   1 root       sys         763810 Apr 28 10:37 test_neu.html.13320

Do a "tail test_neu.txt" to see the last successful run command (headlines).

Do a "test_neu.txt.13320" to see the output of last command, this gives you often
a hint where cfg2html hangs, for example waits for a keystroke etc.


Building cfg2html (Debian/Ubuntu)
---------------------------------

0.)   sudo apt install alien fakeroot devscripts lintian gawk

1.)   cd ~/cfg2html/cfg2html/linux/packaging on master [!$]

      Note: It's important to be in the correct directory, otherwise the build will fail.
      Note: A valid mail address is required in the changelog file.

      dch warning: neither DEBEMAIL nor EMAIL environment variable is set
      dch warning: building email address from username and FQDN
      dch: Did you see those 2 warnings?  Press RETURN to continue...

      export DEBMAIL=your.name@domain.com
      dch -v 7.1.3   ### apt install devscripts, 207 newly installed/43.8 MB
      dch -i         ### here you document your changes, -i increases the version number

2.)   cd ~/cfg2html/cfg2html
      make deb


 _____     ____
|_   _|__ |  _ \  ___
  | |/ _ \| | | |/ _ \
  | | (_) | |_| | (_) |
  |_|\___/|____/ \___/


See github issues

/* end */
