SourceForge.net Logo

Click here to download the latest version








The Guide





MD5Guard - The MD5 Based Files' Concistency Monitoring Client/Server System












General Information

The system consists of two programs:

MD5Guard is the client-server application used for remote monitoring of files' concistency via a network. It uses MD5 hash for files' concistency check. The code is written in ANSI C and tested under FreeBSD and Linux. It is very accurate, strict, well structured and documented. The 'Doxygen' program is used in addition to expressive commentaries to make the code really easy to understand. It may be successfuly used for education purposes.

The program consist of two parts: MD5Server and MD5Client. The host running the MD5Server periodically receives connections from the hosts that run the MD5Client. The MD5Server authenticates the clients using Acess Control List. During the session the MD5Server sends to the clients names of files and the clients responds their MD5 hash. The list of file names is configurable at per-client basis. Any abnormal behaviour (MD5 hash mismatch, a broken connection, a client was not connected during expected period of time, attempt of some client to connect twice at same time, the maximal amount of simultaneously connected clients was acheived e.t.c.) is logged via syslogd. This information may be easily redirected to an email of a person that is responsible for an administration of the host or may be used to run some program that will try to repair an inconsistence in an automatic mode and report results.

MD5Guard is a very easy configurable application. The client's configuration is only one line in cron.conf. Name of MD5Server and its port number are optional (of course, in a real environement the servers name, if it is different from 'localhost', is required).

Configuration of the MD5Server is also very simple. All command line parameters have reasonable default values. There are only two actions to perform: to create a working directory that will store the clients' configuration files and to add an entry to the configuration file of syslogd. There is the shell script for automation of these tasks. A client's configuration file is a list of files to check on the client's side. Initially the file contains only names of files. During a first session each file name is complemented by a value of its MD5 hash. This step is logged via syslogd. During all sequential sessions only anomalies are logged. In the case of MD5 hash mismatch the new value of the hash replaces the old one and the event is logged only once. This behaviour intended to reduce the need of an administrative intervention during massive upgrades of the clients. The MD5Server manages the clients' configuration files in a very intelligent form: it is able to recognize and repair almost any anomalies or corruption of the data. All these events are logged also.

In a next releases of the MD5Guard I plan to improve the robustness and the reliability of the system by introducing additional features to the program, such as timeouts, configurable (now it is defined at compile time) limit of the maximum number of concurrent connections and detection of brute-force attacks to prevent the input queue overflows. Another thing is to switch the build infrastructure to the GNU autoconf/automake tools.





The MD5 Client:

The MD5 Client performs the following actions:

The main program function of The MD5 Client is in the src/md5client/client.c file. There is the colored, linked, easy browsable and documented source code of The MD5 Client generated with the "Doxygen" and "Dot" programs.





The MD5 Server:

The MD5 Server performs the following actions:

The function 'serveclient' performs the following actions: The main program function of The MD5 Server is in the src/md5server/master.c file. There is the colored, linked, easy browsable and documented source code of The MD5 Server generated with the "Doxygen" and "Dot" programs.





Compilation

To build all components of the system on Linux execute in the MD5Guard-0.1 directory the following command: 'make' or 'make distclean all clean' to completely rebuild the program and remove all object files. On FreeBSD type 'gmake FREEBSD=yes' instead of 'make' (this is true for the following examples too). If you want to debug the program, add 'DEBUG=yes' to the make parameters. (For example, under FreeBSD: 'gmake FREEBSD=yes DEBUG=yes distclean all clean').

Before first start of the server you must configure it.

To generate an easy browsable, colored and linked documentation of the source files you must have installed the "Doxygen" and "Dot" programs. To build the documentation run 'make docs'. This will create the documentation in HTML format.

There are links to it:

To remove the documentation run 'make cleandocs'

The documentation for The MD5 Server and The MD5 Client stored in the src/md5server/doc/ and src/md5client/doc/ directories respectively.

All source files are stored in the src/ directory.
The file src/defaults.h contains definitions of all default values of the programs.
The source files of The MD5 Server stored in the src/md5server directory.
The source files of MD5 Client stored in the src/md5client directory.

There are Makefiles in all of the directories:

Each makefile have following rules:

The main Makefile that stored in the MD5Guard-0.1 directory have two additional rules:

The program tested on following systems:





Configuration

To run the server you must create two directories:

For each client you must create the configuration file in the working directory of the server. The name of the file MUST be equivalent to the output of the command 'hostname' on the client's host.

There is the sample configuration file contents:

600
0
/etc/fstab
/etc/syslog.conf
/bin/sh
/bin/bash

The first string of the file that the server will 'understand' is the string that represents a non negative integer number. All other strings will be silently ignored. The number is a maximal amount of seconds between two successive connections of the client. The DUMMYTIME value (defined in the file src/defaults.h as zero) means that the client is temporary disabled.

The second 'understandable' string must have the some format - a non negative integer number. And, as before, all other strings will be silently ignored. The string stores the time of last connection of the client (the value of time in seconds since 0 hours, 0 minutes, 0 seconds, January 1, 1970, Coordinated Universal Time). For a new configuration file you can write zero here.

The next string must be an absolute name of file (begins from '/').

The rest lines of the file must be absolute names of files or MD5 sums. Each MD5 sum references the previous name of file. After each connection of the client the file is rearranged. If some of sums are changed - the server replaces the old sum by new one and sends an one-time warning to the system log.

To catch all server's messages and warnings, you need to configure the system logger. If your system logger is syslogd, you can use the script configure-syslogd.sh to configure the syslogd. You must be a root to do it. All server's messages and warnings will be stored in the file /var/log/md5server.log . You can monitor the file with the command 'tail -f /var/log/md5server.log'. Unfortunately, the GNU syslogd (used in Linux) can not be configured to redirect the output of the specific program to specific file. So, the file /var/log/md5server.log will contain messages of other programs in addition to the messages and warnings of The MD5 Server. Use the command 'grep md5server /var/log/md5server.log' to filter them.

And finally, you must configure the cron daemon on the client's host to run the md5client each period or less seconds.





Usage

To get the description of all available command-line options of the server or the client, run them with '-h' option.
There is the sample output:


./md5server -h

MD5 Server usage:
    md5server [options]

Available options:
  -h                print this message
  -d directory      the working directory name (default is /tmp/md5server)
  -p port_number    TCP port to open (default is 1975)
  -t seconds        the time between two successive scans
                    for expired clients (default is 60)



./md5client -h

MD5 Client usage:
    md5client [options]

Available options:
  -h               print this message
  -a address       the address of md5server (default is localhost's name)
  -p port_number   TCP port of md5server (default is 1975)