· Overview
· System requirements
· Installation
· Configuration
· Run the program
· Questions and answers?
· Disclaimer and licence terms
| Rsyncmrtg is a program written in Perl that analyzes the logfile from the backup/synchronization program Rsync. The logged data will then be presented graphically with MRTG (Multi Router Traffic Grapher) and a webserver. Below is a list of key features: |
|
|
· Return the last occurrence of "read/write" data for the module of choice to MRTG. · Return the last occurrence of "total used block" data for the module of choice to MRTG. · All rsync modules are treated separately and will not have influence on other modules. · List all data found to check if the program is working correctly. |
|
|
|
This help file will present and explain the configuration of Rsyncmrtg, MRTG and your UNIX operating system to get useful statistics. There is also a questions and answers section. Any questions regarding this program (please check the QA section before sending any questions) and bug reports may be sent to the author to the following address:
Mail : rsync[at]timewind.se |
|
|
| Please read the disclaimer before using this program. |
|
Back to index |
| Minimum requirements: |
|
|
|
· A Unix operating system: Rsyncmrtg has been tested on FreeBSD and Linux. · Compatible versions of Perl, MRTG and Rsync. A webserver may also be needed. · Reasonably fast hardware with enough memory and diskspace for the necessary components. |
|
Back to index |
| This manual page does not cover the installation of Perl, Mrtg, Rsync and Apache. Please read the documentation provided for these software packages. |
|
|
|
· Download and install Perl from: www.perl.org · Download and install Mrtg from: www.mrtg.org · Download and install Rsync from: samba.anu.edu.au/rsync · Download and install Apache from: www.apache.org |
|
|
| Rsyncmrtg is tested on rsync versions 2.6.2 to 2.6.8. It is recommended to upgrade to at least 2.6.3 as Rsyncmrtg will much run better on versions later than 2.6.2 due to changes in the rsync logging function. The perl version should be 5.6 or later. The MRTG version is probably not critical. |
|
|
|
Install Rsyncmrtg: |
|
|
|
· Download and install Rsyncmrtg from: www.timewind.se · Unzip and untar the software. · Copy the rsyncmrtg program file to a directory of your choice. · Set owner to root and set the executable flag for rsyncmrtg file. · Copy the rsyncmrtg.cfg and rsyncmrtg.conf to the /usr/local/etc/mrtg/ directory (default). |
|
|
| If the rsyncmrtg.conf must be located in any other directory than the default value, the rsyncmrtg perl file (and the constant $rsmconfig) must be edited. |
|
|
|
Back to index |
| This manual page does not cover the general configuration of Perl, Mrtg, Rsync and Apache. Please read the documentation provided for these software packages. |
|
|
|
Configure Rsync: |
|
|
| Configure and start your rsync server. You must have the log file command enabled in the rsyncd.conf configuration file. There must be a log file available with some data if rsyncmrtg should be able to do something useful. Rsyncmrtg may not work with custom log formats. The format for the log file command is shown below: |
|
|
|
log file=/var/log/rsyncd.log |
|
|
|
All modules which rsyncmrtg will process must exist in the rsyncd.conf file. Rsyncmrtg will also check and use the "max connections"
statement which must be numeric. |
|
|
|
Configure Rsyncmrtg: |
|
|
| Edit the rsyncmrtg.conf file and set the path to the rsync configuration and binary files. The default values are often correct. The parameter you probably want to change is the path to the directory where rsyncmrtg should write the statefiles. The statefile are a temporary storage for the output of the last rsyncmrtg run. If no data is found the data from the statefile are returned to MRTG. You may also set the strings to search for in the rsync logfile. In older Rsync versions you may have to change these values. The format for the configuration parameters (with the default values) are shown below: |
|
|
|
cfgfile = /usr/local/etc/rsyncd.conf binfile = /usr/local/bin/rsync statdir = /usr/local/www/htdocs/rsyncmrtg/ sendstr = sent readstr = received |
|
|
| Edit the rsyncmrtg.cfg file and add code for your rsync modules. This helpfile does not cover the usage for the MRTG configuration files. See the mrtg documentation for details. The command that will run the rsyncmrtg program is shown below: |
|
|
| Target[home_rw]: `/usr/local/bin/rsyncmrtg -rw home` |
|
|
| Change the second argument to the rsyncmrtg program which in this case is "home" to the actual rsync module from your rsyncd.conf file. Change the target name which is this case is "home_rw" to a name of your choice. Remember that the target name must be unique for every module. You will probably also want to change the "Workdir" parameter to the directory where MRTG should write the resulting html and png files. |
|
|
|
Back to index |
| Rsyncmrtg is intended to be used in combination with MRTG to produce statistics and graphs of transferred data to and from a rsync server. The program can also run stand alone from the command line to verify that no errors are generated and to check the accuracy of the returned data. The usage of rsyncmrtg is shown below: | ||||||||||||
|
|
||||||||||||
| Usage: rsyncmrtg [switch] module | ||||||||||||
|
|
||||||||||||
| where "module" is a rsync module. The module argument cannot be omitted. The module name must also exist in the rsyncd.conf file and must not be ambiguous. The switch argument is optional. Only one switch can be used at the same time. The "-rw" function will be used if no switch is provided. The switches which are recognized are described below: | ||||||||||||
|
|
||||||||||||
|
||||||||||||
|
|
||||||||||||
| First run the rsyncmrtg program from the command line to verify that there are not any error messages. The command: | ||||||||||||
|
|
||||||||||||
| /usr/local/bin/rsyncmrtg -rw home | ||||||||||||
|
|
||||||||||||
| should return data which should look something like the example below: | ||||||||||||
|
|
||||||||||||
|
1048576 69 1:00 Rsync v2.6.3 @ localhost |
||||||||||||
|
|
||||||||||||
| The first line is data read. The second line is data written. The third line is the current system uptime and the fourth line is the rsync version and the system hostname. The second line will return a zero "0" if the "-t" switch is used. Any error messages must be corrected before using rsyncmrtg with the MRTG program. | ||||||||||||
|
|
||||||||||||
| If everything seems to be ok you may invoke mrtg from crontab to create the statistics and graphics: | ||||||||||||
|
|
||||||||||||
| 0 * * * * /usr/local/bin/mrtg /usr/local/etc/mrtg/rsyncmrtg.cfg | ||||||||||||
|
|
||||||||||||
| Configure crontab to run rsyncmrtg some time after each rsync to be sure of the accuracy of the statistics data. | ||||||||||||
|
|
||||||||||||
|
Back to index |
|
· How do I change the folder to store my collected data? The directory where the statistics data is stored is determined by the rsyncmrtg.cfg file and the "workdir" statement· How do I change the colours and properties of the grahpics? These properties are set by statements in the rsyncmrtg.cfg file. These are MRTG statements and are not thoroughly covered by this help file. Read the documentation for the MRTG program.· How do I change the directory for my config files? The rsyncmrtg.cfg file can be located anywhere in your filesystem, The location for the rsyncmrtg.conf file is set in the rsyncmrtg perl script. You may change it by editing the path provided in the statement "$rsmconfig".· There is data in the logfile but Rsyncmrtg does not find it? Compare the "search strings" parameters in the rsyncmrtg.conf file and the actual logfile. Rsync may have changed the logfile structure. In older versions the sendstr entry should be set to wrote and the readstr parameter to read.· Why does rsynmrtg sometimes "lose" data found in the logfile? The rsync logfile format is not very easy to interpret in versions prior to 2.6.3. The result are only connected to the module name with the process id which may be altered by another rsync process or another program. Unfortunately, this behaviour cannot be changed with the rsync logformat command. As a consequence of this, I do not recommend running more than one sync simultaneously in version older than 2.6.3. Rsyncmrtg does use some algorithms which will try to determine which data is associated to the actual module but errors may occur. Rather than returning wrong data, rsyncmrtg will return the data found in the statefile. You can check how well rsyncmrtg are performing by running the program with the "-pr", "-pw" or "-pt" switches from the command line. This procedure will not alter the data in the statefile. |
|
Back to index |
| Please read this chapter carefully before using rsyncmrtg. |
|
|
| RSYNCMRTG is released as free software and is written for the FreeBSD operating system. RSYNCMRTG will probably also run on most other unix flavours (including linux) with small or no changes. |
|
|
| RSYNCMRTG is released WITHOUT ANY WARRANTY and the author cannot be held responsible for any consequences of any use of this program. |
|
|
| Rsyncmrtg is unsupported. Any questions regarding this program are answered when there is time available. Relevant questions will be added to the questions and answers section in future releases of this document. |
|
|
| Please note: If you use rsyncmrtg, you do so at your own risk. The author cannot be held responsible for anything that results from the use of this application. |
|
|
|
Back to index |
Rsyncmrtg help and manual page v1.00 © 2006-05-05 by Stefan Sundberg (rsync[at]timewind.se)