NAME

Gluon - Decision-tree monitor daemon

SYNOPSIS

gluon.pl [--configfile config-file ] [--treefile tree-file ] [--daemon] [--scriptdir script-dir ] [--logging integer ] [--logfile log-file ] [--duser user ] [--dgroup group ] [--sleep integer ] [--debug integer ] [--version] [--help] [--manual] [--]

DESCRIPTION

Gluon is a simple decision-tree daemon, written in Perl, that executes external programs (scripts) to determine the path-flow within the decision-tree. It essentially operates as a basic IF-THEN-ELSE expert system that can be used to monitor and take action.

REQUIRES

Tree::Simple Tree::Parser Getopt::Long

and a few others in the Perl Core.

OPTIONS

Options are processed in the following sequence:

Application defaults -> Configuration file -> Command line options

The only exception to this is supplying an alternative configuration file in the command line options. The contents of that configuration file are then overridden by any other options supplied on the command line.

--configfile, --config, -c config-file
Use alternative configuration file. Default is gluon.conf for non-root users and /etc/gluon.conf for root.

--treefile, --tree, -t tree-file
Use alternative tree file. The filename must end in tree. The location can either be absolute, or relative to the gluon.pl script.

See the FILES section for further information.

--daemon, -r
Gluon runs as a daemon if set or runs just once if not set. As a daemon it will run continuously in the background with sleep setting the timeout between successive runs through the tree.

--scriptdir, --scripts, -s script-dir
The scriptdir options sets the default directory for the action scripts. Because there could potentially be quite a few scripts, it made sense to place these all together in a directory within the Gluon directory. With this option you don't have to keep adding the path to the ``Action'' variable within the tree file. Of course, absolute paths are also allowed.

--logging, -l integer
The logging option sets whether Gluon writes to a log file or not. Values are: 
      0 - No logging
      1 - Warnings only
      2 - Info + Warnings
      3 - Debug + Info + Warnings
      4 - Verbose Debug + Info + Warnings

--logfile, -f log-file
The logfile options sets the location of the log file. If gluon.pl is run as root, and the default value is still set (gluon.log) then the default automatically changes to /var/log/gluon.log

--duser, -u user
The duser option sets the username (actually, the uid) with which Gluon will run as a daemon. For this to work Gluon must be run as root. If it is run as a non-root user, then the daemon will keep that uid. The username must exist on the system and have a valid uid.

--dgroup, -g group
The dgroup option sets the group with which Gluon will run as a daemon. See duser for more information. The group must exist on the system and have a valid gid.

--sleep -p integer
The sleep option sets the timeout period between runs through the tree. So, when Gluon is first run, it cycles through the tree and when it comes to completion it sleeps for the number of seconds set here. Value is in seconds.

--debug, -d integer
The debug option sets whether Gluon prints out debug information. If this is set, Gluon writes the debug output to STDOUT. Values are: 
      0 - Fatal errors only
      1 - Warnings + Fatal errors
      2 - Info +  Warnings + Fatal errors
      3 - Debug + Info + Warnings + Fatal errors
      4 - Verbose Debug + Info + Warnings + Fatal errors

--version, -v
Displays the Gluon release version.

--help, -h, -?
Displays help information.

--manual, --man, -m
Displays full manpage.

--
Terminates command line arguments.

RETURN VALUE

If run in single mode (not daemon), Gluon will exit with a return value equal to one hundred (100) plus the sum of the exit values of each tree branch, unless there is an error.

To allow for user determined exit values, Gluon uses exit values of less than 100 for its internal error values. See the ERRORS section for further details.

ERRORS

Returns >100
User determined exit values (Not an error)

Returns 0
No error, exited normally.

Returns 1
A fatal error within Gluon occured.

Returns 2
Null return from main tree process.

Others
Can be caused by compilation or perl module errors.

FILES

gluon.conf
This file contains configurations settings for Gluon. The options set here will override the application defaults, however, anything passed on the command line will override these.

Please see the OPTIONS section of this manpage for futher details.

gluon.tree
A tree is basically a hierarchal structure composed of nodes, each having zero or more child nodes. In the world of Gluon there are four types of nodes.

These are:

Action, Result, Goto and Exit (and technically root node, but we're only interested in its children).

It is the structure of the tree, using the above four nodes, that determines the behavior of Gluon. Gluon allows for three different tree formats:

Dot-separated:

E.g.

      |1 Node A
      |1.1 Child of A
      |1.2 Another child of A
      |2 Node B
      |2.1 Child of node B
      |2.1.1 Child of the 2.1 node

Space indented (two spaces):

E.g.

      |Node A
      |  Child of A
      |  Another child of A
      |Node B
      |  Child of node B
      |    Child of the 2.1 node

Tab indented (Spaces used below, but you should use tabs):

E.g.

      |Node A
      |        Child of A
      |        Another child of A
      |Node B
      |        Child of node B
      |                Child of the 2.1 node

Here the ``|'' characters represent the left side of the tree file.

Using this method we can easily build up a tree structure. Now, the above examples are all quite generic, however Gluon requires the node labels (eg. ``Node A'' or ``Node B'' etc.) to have a specific format. As stated above, there are four different node types, each with a particular purpose. The structure of Gluon tree files is quite specific and takes the generic form of:

      |1 Action Node
      |1.1 Result Node
      |1.1.1 Action/Exit/Goto Node
      |1.2 Result Node
      |1.2.1 Action/Exit/Goto Node
      |2 Action Node

So, the children of an Action node will generally be Result nodes and the children of a Result node can be either Action, Exit or Goto nodes. Gluon does not enforce any particular structure, so it is technically possible to set an Exit node as a child of an Action node. This could have the desired effect, but could quite easily have unexpected effects (Gluon processes the nodes as it finds them). The process of moving through the nodes of the decision-tree (following a path-flow) is called a cycle or run.

As you can see from the example above, Gluon allows for multiple ``root'' nodes. So, in the example the first one is ``1 Action Node'' and the second is ``2 Action Node''. Once the cycle of one node branch is finished, Gluon simply moves on to the next. This allows one to run multiple tests from one instance of the Gluon daemon. However, this can be a problem when using Goto nodes for two reasons. Firstly, the Goto node searches across all nodes, not just the branch it was called from. This is actually quite useful as it allows one to jump across to otherwise unrelated branches. Secondly, if Gluon gets stuck in a Goto loop, it will never run through the other brances (until the Goto loop disappears).

The Gluon nodes are:

The Action node
Name ``Name'' : Action ``File'' : Log ``Log message''

The values inside the ``'' can be set as required. The Name variable (e.g. ``A Name'') must be a unique name to describe that node and can be made up of letters, numbers, spaces and ``.'' ``_'' characters. The Action variable must contain a path/filename of an executable. Gluon executes this file and records the exit status. It is this exit status, along with the Result node that determines the next step in path-flow through the tree. This variable can contain all the previous characters and also ``/''. Finally, the Log variable is an optional variable which, if not empty, contains a message that gets written to the log file if logging is switched on.

The ``Result'' node
Result ``Expression''

This node is simple in that it only has one variable, but the contents of the variable itself can be quite complicated. The expression is made up of 3 parts:

  1. The ``RESULT'' keyword

  2. The Comparison operators == != > < >= and <= (generically called C below)

  3. The Logical operators && and || (generically called L below and are optional)

The expression must at least be of the following form ``RESULT C integer'' but can be expanded to create more complex statements using the logical operators. So, an example Result node might be:

Result ``RESULT > 0 && RESULT < 10''

or

Result ``RESULT != 0''

The ``RESULT'' keyword is then replaced by the exit value of the previous Action node. If the expression is true then this path is followed. Else, Gluon moves on to the next Result node.

The ``Goto'' node
Goto ``Node name'' : Log ``Log message''

This is quite an interesting node. It allows one to jump from one part of the tree to another. It does this by looking for an Action node with a Name variable that matches the value set in the Goto variable. Once it finds a matching node, it will sleep for the set timeout period (see the OPTIONS section for more details), then proceed from the found node. One thing to take note of is that if nothing in the path-flow up to the goto changes, Gluon will simply loop continuously down this path. That is why the timeout period was introduced, as it creates the effect of starting a new run.

The ``Exit'' node
Exit ``Integer''

This nodes terminates a run. If Gluon was set to run once only, then the script will exit with an exit code as set by the Exit variable. This is useful as it allows one to use Gluon within another Gluon tree. This could be to break up anotherwise complicated tree into smaller, more managable trees. If Gluon is running as a daemon, it simply terminates the run and does not pay attention to the exit value.

SEE ALSO

perl (1) the Tree::Simple manpage the Tree::Parser manpage the Getops::Long manpage

CAVEATS

Exit value of compilation or perl module errors might clash when expecting Gluon to return a similar value.

Environmental variables could be an interesting way around this.

BUGS

No known bugs at present. Please submit bugs to:

gluon-bugs at lists dot sourceforge dot net

RESTRICTIONS

Character restrictions apply to node variables. Allow characters are:

Name
A-Z a-z 0-9 _ .

and spaces.

Action
A-Z a-z 0-9 _ . /

and spaces.

Log
A-Z a-z 0-9 _ .

and spaces.

Exit
0-9

Result
The ``RESULT'' keyword.

!= == > < >= <= 0-9 && ||

and spaces.

Goto
A-Z a-z 0-9 _ .

and spaces.

Please note: This affects allowed filenames and paths.

AUTHOR

Fraser Scott fraser at 0x10 dot com

For support please email:

gluon-support at lists dot sourceforge dot net

or visit http://gluon.sourceforge.net