
Here you can find some "tutorials" for the daxfid script:
1. Let's follow a rule from the XML to the execution, within the daxfid program.
2. How to write a plug-in for the daxfid program.

For any other informations you can always read the code or
ask me (see AUTHOR.txt)


  1. Let's follow a rule from the XML to the execution.

Take a rule like 'identd.xml' in the '/etc/daxfid/xmlrules.d/'
directory.
If you're running daxfid in runlevel 'default', every file in
the '/etc/daxfid/default.d/' directory that begins with an 'S' and
ends in '.py' will be executed as a plug-in; among these files
you find 'S20identd.py'; in this file the 'run_this()' function
simply call the 'processXMLFile()' function that parse a
given XML file (as you can guess 'identd.xml').

The daxfi.Firewall.newRulesFromXMLFile() method opens the file and
parse the XML using a RuleBuilder object that takes the data and
apply to the various sections some functions that transform and
normalize the data (e.g., the host name is tranformed in dotted
notation plus a netmask; protocol and port names are translated
into numeric values and much more).
Other transformations for XML attributes and sections are defined
in the firewall specific Rule class.
That's all done via the 'first_transformation' and 'section_transformation'
variables of the Rule class; these are defined in firewall-specific
subclasses since they depend on the kind of firewall.
The return of the RuleBuilder object, after all these elaborations, is
always a list of one or more Rule objects that can ben
used to create the string to be executed on the command line.
A Rule object has - amongst other things - a RuleData object that describes
the various options for the current rule.

Note: two Rule are considered equals if and only if the two RuleData objects
are the same.  This is the reason of many transformations.
That list of rules is then given to the processRules() function that,
for every rule in the list, call the method getRuleCommand()
of the Rule object that returns a string useful to be run at
the command line (note that - obviously - the Rule object depends
upon the kind of firewall you have); the Rule object do another set
of transformations useful to translate the RuleData object into commands and
options for the specific firewall.


  2. How to write a plug-in.

A plug-in must contain a Python function with name run_this().
You define a function in this way:

def run_this():
    [CODE]

Please refer to the Python tutorial if you want to write your
own plug-ins.
I highly recommend Python to everyone since it's a _wonderful_
language (well, maybe *my* Python isn't wonderful at all, but... ;-)

The only useful thing a plug-ins can do is to process a rule
or a list of rules: a rule (or a set of rules) can be read
from an XML file or create a rule by itself; after that the
rule (or rules) must be processed.

Along with the run_this() function, a plug-in can also define the
PERSISTENT variable; if this is present, and is a numeric
value greater than zero, it's taken as the delay in seconds
to wait before this plug-in is called again.
If zero or not defined, the plug-in is called only once.

Let's take a look at two tipical plug-ins:

/etc/daxfid/rules.d/conn_up.py:
simply call a function that process an XML file; the file is parsed,
a set of rules is returned and then processed (i.e. executed).

/etc/daxfid/rules.d/tcplisten.py:
this plug-in doesn't use an XML file but generates by itself a
set of rules that will be processed.
Moreover this plug-in define the PERSISTENT, specifying that it
want to be executed every five seconds.
How the rules are created?  Via the createNewRules() function, that is
a wrapper for a method of a daxfi.Firewall object; this function takes
many parameters useful to defines a simple rule (many specific
option are still missing).

Inside a run_this() function you can use some functions and variables
made available from the daxfid script and daxfi package.

Variables:
XMLRULES_DIR: directory where the XML files are stored.
REMOTE_IP: the IP of the remote end.
LOCAL_IP: the IP of this machine.
INTERFACE: the interface we're using.

Functions:
processRules: call this function with a rule or a list (or a tuple)
              of Rule objects.
              This function execute the command generated by the
              given rule.
processXMLFile: parse and process an XML file.
processXMLString: same as above, working with a string.
createNewRules: create a new rule.
storeData: save a useful informations for
           subsequents runs of this plug-in.
loadData: load previously saved data.
is_daemon: return true if the rule is running in daemon mode.
sl_print_info, sl_print_warning and sl_print_error: print a
               given string in the system logs, with differents
               priority levels.
checkRule: returns true (exactly it returns the rule number
           in the proper chain) if a given rule is already active.
listRules: list rules in the given chain (return a list of Rule objects).
listXMLRules: list rules in the given chain (return a list of XML strings).


