HOWTO for FREESCO 027

This page is viewed Counter times

looking for the 0.3.x angel package howto page? Click here

Requirements:

  • a harddisk based FREESCO box (due to the perl package this will *not* run on a floppy, sorry)
  • perl version 5.003 or 5.61 package (see http://www.freescosoft.com to download)
  • a web server (i.e. enable the FREESCO public webserver in secure ('s') or public ('y') mode).
  • a human (preferable) system admin
  • some time

The angel installation script will check for the presence of the perl package. It will *not* work with the perl that is part of the Apache package.

 

Step 1: install angel package on your FREESCO box

Login as root using telnet, ssh or direct console access. The sample install below loads the package from this server, but I suggest you use the FREESCOSoft search script to locate the mirror closest to you. The next table shows a few mirror locations:
if you live here use:  

installpkg http://www.freescosoft.com/home/0.2.7/dingetje/angel

installpkg http://tecknojunky.dyndns.org/freescosoft/0.2.7/dingetje/angel
if you live here use:
woon je hier gebruik dan:   

installpkg http://freescosoft.freebse.nl/0.2.7/dingetje/angel

Optional, you may also want to install the additional angel_plugins package. This adds 7 more plugins to the list. This package can safely be installed on top of a working angel configuration. After the angel package has been installed/configured and checked for proper operation. Type installpkg <url>/angel_plugins. The <url> is the same as for the angel package from the above table.

Sample installation

click on the thumbnail for a bigger image

Step 2 Check if it works...

wait a while (to allow the just started angel script to generate the first result page) and then point your favorite web browser to http://your.freesco.ip/angel/html/index.html

Where your.freesco.ip is the IP address of the FREESCO box in your LAN. The default 'angel' configuration will measure 4 items of your FREESCO box, namely the HTTP ports 80 (/www), 82 (/wwa for the admin page) the free disk space and the system load.

Sample (default) result page

click on the thumbnail for a bigger picture.

The above screen shot shows how things should look (providing your disk space, load, etc. is OK). Check that the time stamp at the 'Last updated:' line is your current server time. If not, you may have to wait a little longer and do a refresh of the page. If after a long enough period, you still don't get an updated display, there is probably something wrong. You may want to check the trouble shooting section below.

Step 3: modify the angel configuration to match your situation

Step 3a

Stop the angel monitor by using the command:

[Linux] rc_angel stop
Stopping angel network monitor... Done

 

Step 3b

Go to the angel configuration directory:

[Linux] cd /mnt/router/packages/angel/conf
[Linux] ls -la *.conf
-rw-r--r-- 1 root root 4977 Sep 16 20:08 angel.conf
-rw-r--r-- 1 root root 1174 Sep 16 22:21 hosts.conf

The 'angel.conf' file contains the HTML header and footer for the generated status page as well as some options to control the angel network monitor. Use your favorite editor to open the file and make modifications if you want. The next table may be of help here.

Options:

comment in angel.conf FREESCO specific/notes
$main::Use_ledsign=0;  ## Should we use ledsign? (Requires Java) default not used
$main::Index_column_width=80;  ## Use -1 for browser automatic .
$main::Index_html_border=1;  ## Table border width use 0 for no border
$main::Error_host_width=80;  ## Use -1 for browser automatic .
$main::Error_label_width=100;  ## Label for errors .
$main::Error_column_width=400;  ## Use -1 for browser automatic .
$main::Error_html_border=0;  ## Table border width .
$main::Remote_cmd="ssh"; ## Remote command (ssh rules) not used in FREESCO version

The next sections in this file can be used to modify the HTML header and footer for the status page and the error page to give the pages the same look-and-feel as the other pages on your site.

#-----------------------------------------------------------------------------
# Main HTML Header
#-----------------------------------------------------------------------------

#-----------------------------------------------------------------------------
# Main HTML Footer
#-----------------------------------------------------------------------------

#-----------------------------------------------------------------------------
# Error Page HTML Header
#-----------------------------------------------------------------------------

#-----------------------------------------------------------------------------
# Error Page HTML Footer
#-----------------------------------------------------------------------------

These sections require detailed knowledge of HTML and if you're not too sure, you'd better leave them as it is.

The last section controls the optional LED sign. This is a java applet that is only added to the generated status page, when the option $main::Use_ledsign is set to 1 (see above). If you want to have a look at it, then go ahead and change this option. The message displayed in the LED sign is default controlled with /www/angel/html/java/ledsign/scripts/angel.led

Step 3c

The other configuration file 'hosts.conf' contains the items you want your guardian angel to monitor. The default package comes with four so called plugins. The angel add-on package angel_plugins adds 7 more plugins to the list. These plugins are all written in perl and are named:

Plug-in Name Package Description
Check_disk.pl angel check free disk space. This script has been modified to be used on FREESCO and can also no longer be used to check remote nodes.
Check_load.pl angel check system load. This script has been modified for FREESCO, it can no longer be used to check the load on remote systems.
Check_tcp.pl angel Check if a specific TCP port is available at a specified host.
Check_ping.pl angel Check if a 'ping' to a specified host is within the specified limits
Check_ftp.pl angel_plugins Check if the FTP server at the specified host + port is responding.
Check_http.pl angel_plugins Check if the HTTP server at the specified host + port is responding.
Check_nntp.pl angel_plugins Check if the NNTP (News) server at the specified host + port is responding.
Check_smtp.pl angel_plugins Check if the SMTP (Mail) server at the specified host is responding. This plugin will use the default port as defined in /etc/services.
Check_pop.pl angel_plugins Check if the POP3 (Mail) server at the specified host is responding. This plugin will use the default port as defined in /etc/services.
Check_dns.pl angel_plugins Check if the DNS (name)server at the specified host is responding. This plugin performs an actual query and is thus preferred over the Check_tcp plugin that merely checks if a port is open.
Check_proc.pl angel_plugins Check if the specified process and number of processes is running on your FREESCO box.

These plugins are located in directory /mnt/router/packages/angel/plugins

The 'hosts.conf' file defines which plugins you want to execute and to provide each plugin with the required arguments. You may want to look at my hosts.conf  here to see what is used to generate this page.

For help on the syntax you may also want to check out the official 'angel' site at http://www.paganini.net/angel and look for the heading Plugin Specific Documentation.

Step 3d

When you have finished editing the configuration file(s), start the monitor again with the following command:

[Linux] rc_angel start
Starting angel network monitor... Done

Final step

Again, wait a while to allow angel to run and then point your browser to /angel/html/index.html to admire the results of your modifications.

 

Other notes:

  • Default the interval for angel executions is set to 5 minutes or 300 sec. If you want to change that, you'll have to:
  1. stop the angel package (see above).
  2. edit the 'daemon' file /mnt/router/packages/angel/bin/angeld
  3. locate the 'sleep' statement in the endless loop (while true) and modify the 300 there to the required interval in seconds.
  4. save the changes and start the angel package (see above).
  • The /mnt/router/packages/angel/html/docs directory contains the official HTML documentation for the angel script. You may want to copy that to your /www/angel/html path too for further reference. The same docs are available on the official angel site.
  • Perl isn't the most CPU friendly script language, so low end FREESCO boxes should probably not install this package, or run it at a low frequency (once every half hour or so). During execution on my box the free memory dropped from 8.5Mb to 6.4Mb, so a whopping 2.1Mb! Again, low end FREESCO box owners should probably reconsider....
  • I have modified some of the plugins to work with FREESCO and have removed the remote command for some of the plugins, since this is a) a possible security hole and b) probably not required for most FREESCO networks anyway.
  • I have added the network log file and last week's archive feature. This way you do not have to keep the angel display open at all time and still have proof of the quality of your ISP...
  • If you do not want to share angel with the world, you may consider moving it to the /wwa directory so it will be accessable only from the secure web server. If you want to do that you'll need to modify the next lines in the /mnt/router/packages/angel/bin/angel script:

    $main::Indexfile = "/wwa/angel/html/index.html";
    $main::Errorfile = "/wwa/angel/html/error.html";

    (line numbers 98 and 99 on my box, your mileage may vary). After this modification, do not forget to move the /www/angel directory to /wwa/angel

 

Trouble shooting

 

 

If your angel status page is not updated, you need to check if the angel package is up and running.

[Linux] ps | grep angel | grep -v grep
19300 S 1 angeld sh/mnt/router/packages/angel/bin/angeld
19302 S 19300 angel perl-w/mnt/router/packages/angel/bin/angel

In the sample output above, you'll notice that both the angeld process is running and lo and behold even the perl script itself is just being executed ;-). You will usually only see the angeld process.

If the daemon is running and you still don't get an update, there may be something wrong in your configuration file(s). If you haven't touched them yet, there is probably something wrong with the angel perl script or your perl installation. You may want to try the following:

  1. stop de angel package (see above)
  2. type the following commands:

[Linux] cd /mnt/router/packages/angel/bin
[Linux] ls -l /www/angel/html/index.html

-rw-r--r-- 1 root root 4205 Sep 20 01:34 /www/angel/html/index.html
[Linux] date
Thu Sep 20 01:35:36 2001
[Linux] /usr/bin/perl -d angel

Loading DB routines from perl5db.pl version 1.0402
Emacs support available.

Enter h or `h h' for help.

main::(angel:79): $main::Version = "0.7";
DB<1> r
Debugged program terminated. Use q to quit or R to restart,
use O inhibit_exit to avoid stopping after program termination,
h q, h R or h O to get additional info. 
DB<1> q
[Linux] ls -l /www/angel/html/index.html
-rw-r--r-- 1 root root 4205 Sep 20 01:35 /www/angel/html/index.html

  1. This verifies that the angel perl script runs without errors and that the index.html has a new time stamp after the completion of the angel perl script.

Hope this helps!

Last edited: September 9, 2002