bcnu Administrators Guide


Undisplayed Graphic

Administrators Guide - Version 1.21

Section 1 - Obtaining and Installing bcnu


Downloading bcnu

You can get the latest version of bcnu from http://bcnu.sourceforge.net/

You can install a source only distribution and build all of the binaries on your platforms, or take the binary distribution which includes precompiled binaries for the supported platforms.

Installing the bcnu master system

One host must be designated as the master system, this host performs many administrative functions e.g.:

• messages and alerts are sent here

• email or pager alerts are processed here

• data files are logged here

• the web server should run here

• new agents, scripts etc are sent out from here

The installation process should be painless on one of the supported platforms. A step by step guide follows. There are a also number of scripts which can help when installing bcnu, these are described in the following sections

Extracting the files

cd to the directory where you want the archive to be extracted to

e.g. cd /usr/local

untar the archive, it will create a directory called bcnu with all of the files under there

gzip -dc bcnu???.tgz | tar xvf -

If you don’t want to use the pre-built executables, go to the section on configuring bcnu for a new platform.

Once bcnu is unpacked, configuration can begin. There are a few files which need to be edited to set things up initially, but once that’s done the only file which needs much maintenance is the agents file.

The new Setup script available in version 1.20 makes it much easier to get bcnu up and running by configuring a working system for you.

Customizing bcnu on the master

Decide on the final location of bcnu (/usr/local/bcnu is the default). If you have unpacked the distribution to another location, then move it to /usr/local/bcnu or wherever you want it to reside now.

If you choose the default, then there are less changes required to the standard scripts.

bcnu runs as an unprivileged user, normally nobody or adm. If you wish to change this, do it now by editing the script /usr/local/bcnu/etc/bcnulocal

Run the install script in /usr/local/bcnu/Setup to set up the environment.

The script will try to guess most settings, it will allow you to change them if you wish but I suggest you accept the defaults the first time you run it. It will update any required configuration files and will install a default agent configuration file for your platform type. This may not be exactly what is required but it should be enough to get you started very quickly.

If there is already a version of bcnu installed, the server will be stopped and the new version will be configured. Any old config and data files will be retained.

The script will add an entry to the appropriate startup file/directory for your platform. (N.B. root access is be required for this).

It will also change permission on some log files to be readable for the unprivileged user which bcnu runs with.

Ownership of all the bcnu files will be changed to the owner and group of the unprivileged user.

Once that's complete you should be able to start bcnu and it should work!

/usr/local/bcnu/etc/bcnud_server start

will start the daemon. Congratulations you have installed bcnu!

For more detailed information on what the installation routine does, or to have more control over your setup .. read on.

Configuration files in the etc directory

several base files will be created in this directory, these are:

bcnud_server : Required

This is the script that starts bcnud. It should be run whenever the system is started up or shut down. You need to change the BCNUHOME directory here if you are not using the default /usr/local/bcnu

bcnuenv : Required

Contains settings for server type, master host etc.The bcnuenv file will be edited based on the answers to the questions in the install script.

You need to change the master host name and the BCNUURL for your web pages here.

bcnulocal : Optional

You can override any configuration settings in this file, on a per host basis if required.

agents : Required

agent config file - required on all hosts with a bcnud daemon. This is probably the most important file. It details which agents are to be run, how often and what they check for.

hostinfo : Optional

configuration file - only required where alert agent is used. It defines the pager and email addresses where alerts are sent.

bcnunet : Optional

configuration file - only required where net agent is used. It defines the hosts and services to be checked.

logpatterns : Optional

configuration file - only required where log agent is used. It defines the log files which can be checked and the patterns to check for.

services : Optional

configuration file - only required if running the net agent against services which don’t appear in the /etc/services file, or if you want a customised connect message.


Section 2 - Testing the installation


Starting the daemon

These changes should be enough to start up the bcnud daemon for testing. If you want you can start it up now with the command:

/usr/local/bcnu/etc/bcnud_server start -a

The -a option tells the server to log when it starts an agent. This will allow you to see when agents are being scheduled correctly. This logging can also be switched on/off by sending the bcnud daemon a USR1 signal.

To test the server you can run the following:

/usr/local/bcnu/bin/bcnu -p localhost

The following type of message should be displayed:

(dns1)bcnud 1.21.1.19, started at 1999-11-22 13.49.34, 0 requests
0 agents loaded,0 enabled

Two log files should have been created as part of this process under the /usr/local/bcnu/logs directory. The main log file is called bcnu.log, the other bcnud.log

The bcnu.log file should show the system startup time. It should also show that one agent has been run, the av agent. This agent is run when bcnu starts or stops. It gives some useful information about the system which is being monitored.

There should also be a file and directory created under /usr/local/bcnu/data/hosts/

called hostname/av

Congratulations you have installed bcnu!

If none of the above is true, you can check the system log, normally /var/adm/messages or somewhere like that. You can also look in the /usr/local/bcnu/logs/bcnud.log file for clues.


Section 3 – Using agents


The agents config file

Once you have the master server up and running you can set up some agents.

To do this you need to edit the agent config file(/usr/local/bcnu/etc/agents), it holds details of all of the agents, how often to run them, parameters etc. a sample is shown below:

#
# standard monitoring agents
#
#agent:net:10.30-18.00:10:12:enabled:$BCNUHOME/etc/bcnunet:
#agent:procs:8-17:10:12:enabled:mysqld httpd in.named inetd:
#agent:fs:0-24:15:8:enabled:/software=80=90 /tmp=90=95 /=90=95+PAGE /usr=90=95:
#agent:logs:0-24:30:4:enabled:/var/adm/messages=$BCNUHOME/etc/messages.warn:
agent:uptime:8-18:15:8:enabled:1=3=5:
#

Agent directory

Agent name

Hours of service

Run every minutes

How often to log

enabled/disabled

parameter

agent

uptime

8-18

15

8

enabled

1=3=5+PAGE

The agent name is the name of the script found under the agent directory, it should be an executable file. Normally a bourne shell script, but can be written in any language.

Hours of service is used to only monitor when you want. Outwith these hours a blackout is in effect, this is shown by a black background in the web monitor. You can specify hours and minutes here to gain finer control, e.g. 23.55-23.55 will run an agent once at 23.55

The frequency of the agent schedule in minutes can be given, this can be any number. e.g 60 will run every hour, 1440 will be once every 24hours. This field may be changed in future to allow times to be entered as well.

The next field defines how often logging of data to the master will take place i.e. status messages will be logged every 8th time the agent is run. Whenever a change of status is detected it will be logged immediately i.e. if the last run was normal and an error is detected it will be logged. A message will always be logged in the file /usr/local/bcnu/logs/message.log on this host for an agent saying whether it was logged to the master or not.

Whether the agent is enabled or disabled initially. If an agent can’t be executed when it is scheduled, it will be disabled in the bcnud daemon, but the agent file will not be changed.

The last field is the parameter field. This is agent dependant and can contain any text except colons. The agent can parse the field using a standard bcnu function. Parameters are delimited by an "=" sign. There may be multiple parameters separated by spaces e.g. see the fs agent above.

In this example the uptime agent has 3 parameters, these equate to:

• number of days up 1

• five minute load average 3

• fifteen minute load average 5

In addition the +PAGE option means that a text page message will be sent if the error threshold is reached.

Change the agent file to enable the uptime agent and run the commands:

/usr/local/bcnu/bin/bcnu -a reload localhost

The reload will take up to one minute to take effect as the agents are reloaded the next time bcnud checks if there is anything to be run, which is every minute.

/usr/local/bcnu/bin/bcnu -a show localhost

This should show something like:

(dns1)bcnud 1.21.1.19, started at 1999-11-22 13.49.34, 0 requests
1 agents loaded,1 enabled
uptime(agent )enabled runs every 15 minutes, next run (14) log(5) mins

This indicates that uptime will run every 15 minutes, it is due to run in 14 minutes and a another status message will be sent after 5 more runs. Check the following files:

• /usr/local/bcnu/logs/message.log

• /usr/local/data/yyyymmdd.log

• /usr/local/data/localhost/uptime

These parameters can all be changed as required and are designed to minimise network traffic and the size of the data files which are produced. But there is nothing to stop you from changing the run period to zero and the log period to zero. This will run the agent every minute and log successful messages every minute. In this case I’d advise you to run the fs agent every minute as well as you are bound to fill up your /usr filesystem with bcnu logs!

Once this is working satisfactorily you can add the other agents as required. Normally uptime, fs, procs, logs, av, retry and admin are used on all systems.

It is necessary to look at each agent and set the thresholds for each client to be monitored on an individual basis as most systems are different.

The net agent

One of the most important agents on the system is the net agent. This agent is normally only used on the master, but can be used on other systems as well to spread the load. Be careful not to run the net agent for the same hosts on different systems, i.e. using the same bcnunet file. This may give wrong results.

net is one of the agents which has it’s own configuration file(s). It uses a file called by default /usr/local/bcnu/etc/bcnunet. This file contains a list of hostnames and services.

The format is:

host service service .....
dns1 bcnu http smtp ....

If no services are listed for a host, then it will be pinged. This means that any device with an ip address can be monitored, e.g. routers, print servers etc.

The bcnu client program is used to connect to services to test their availability. If a host or service doesn’t respond within 30 seconds it is tried 3 times then an error is logged.

Multiple bcnunet files can be defined if required as their names are passed to the agent as normal parameters in the agents file.

Admin agents

av, retry, admin

Once you have all your agents running, you can add the admin agents. Normally you want to have the av, retry and admin agents running on all bcnu systems. None of these agents require any parameters.

Master agents

alert

On the master system you will have some additional agents running. alert is used to monitor for error conditions and take appropriate action, e.g. send you some email or just run the buildweb script right away.

The target for alerts are held in the file /usr/local/bcnu/etc/hostinfo on the master. Email addresses, pager numbers etc are stored here.

buildweb

Buildweb is one of the most important agents where the dynamic cgi scripts are not being used, it is the agent which builds the web pages for all of the data logged on the master host. As it can be resource intensive on very large systems it should be run regularly but not too frequently. I normally run it every hour, if an error comes in during that time it is run again by the alert agent anyway, but again it is up to you how often you want it to run.

Special agents (007!)

vmgt

If you have a system which uses disk mirroring on solaris,aix,linux or hpux you may be interested in the vmgt agent which monitors the status of mirrors and hot spares and lets you know when one or more goes out of sync.

ckbcnu

This is a simple agent which runs on a server other than the master, to check that the master is OK, the host running this needs to have some way to alert the admin that something is wrong e.g. using the bcnualert agent.

upgrade

This agent is run when upgrading bcnu automatically. The script upgrade_bcnu will set this agent to run on the client to be upgraded and it will pull down the update, upgrade itself and restart bcnu.

proxy

There are a few special agents which may be of use but are not always required. The first is proxy, this agent is used to gather data to be forwarded to the master server. It may be useful where there is not a direct route between the master and all of the systems to be monitored. To use proxy, the proxy agent should be scheduled on one system. The clients which are going to use the proxy should then set their BCNUHOST variable to point to the proxy server. They will log all data to that server, which will pass it on to the real master. The proxy agent should run regularly to make sure that errors are reported asap.

proxy can also be used to mirror all data sent to the master on another system. All that is required is to run proxy on the master system with the host name of the copy as a parameter in the agents file.

discover

Another special agent is discover. This is a quick and dirty way of setting up a bcnunet file. You normally would run it by hand after editing it if necessary. If you run it as it stands, it will check every host in your /etc/hosts file for the following services: bcnu,http,ftp,smtp,telnet

If it gets a response from these it will create an entry for that host with all of the services it found in a file called etc/discover which can be used with the net agent. If you want to add or remove services you need to edit the agent script.

config (experimental)

Lastly the config agent can be used to gather useful configuration information from your clients and log it centrally. This can be used for disaster recovery or even just an easy way to document how systems are setup.


Section 4 - Using bcnu with a web server


If you are using bcnu with a web server then there are some additional steps required to get it working.

There are two options for bcnu and a web server, the first is to run the buildweb agent periodically to build static web pages based on the data found. This is fine, but is not very dynamic and can be wasteful if nobody is looking at the pages.

The second option is to use the cgi scripts supplied to dynamically build a picture of what is going on. This has the advantage that it is an up-to-date view of the system, and there is also some additional functionality. The disadvantage of the scripts is that if there are a lot of people monitoring the system then performance may be affected - the very thing we are trying to prevent!

To enable the web access, create a symbolic link from the www directory of bcnu to somewhere which is visible to the web server. e.g.

ln -s /usr/local/bcnu/www /home/jap/public_html/bcnu

Modify the /usr/local/bcnu/etc/bcnulocal script to change the BCNUURL variable to reference this location e.g.

BCNUURL="/~jap/bcnu"
BCNUPASSWD="/usr/local/etc/httpd/security/it.passwd"

The BCNUPASSWD entry is a standard apache passwd file which can be used to control who can use the ignore feature of the cgi scripts.

Depending on how the web server is configured it may also be necessary to add the following entries to the appropriate config file e.g. (httpd.conf, access.conf or srm.conf)

AddHandler cgi-script .cgi
<Directory "/home/jap/public_html/bcnu/cgi-bin">
Options ExecCGI FollowSymLinks
</Directory>

You will need to do this if the perl scripts are displayed when you access the bcnu.cgi page.

All of the pages should now be created correctly and be accessible.

If your version of perl is not at /usr/local/bin/perl I’m afraid you’ll need to edit the first line of the scripts in the cgi-bin directory.

Run the buildweb script now and then access the url:

http://hostname/~jap/bcnu/summ.htm

Try the cgi version at:

http://hostname/~jap/bcnu/cgi-bin/bcnu.cgi

If you are using the builtin web server the variable should be:

BCNUURL="/www"

and the url for the buildweb files(cgi is not available - Yet!) will be:

http://hostname:6666/www/summ.htm


Section 5 - Configuring bcnu clients


Configuration of the clients should not be done until you have a working master system. This process is exactly the same as above for the master except that it is possible to set up a standard bcnu installation, which can be copied to multiple clients with only minor changes required.

Once all your settings are configured you can run the client_build script in /usr/local/bcnu/scripts/client_build to build a tar file which can be copied to all of your clients.

You then untar as above and run the Setup script.

If you are using the same bcnu home directory name as on the master then the only file which will need to be customized is the agents file for this client.


Section 6 - Configuring bcnu for a new platform


Building the binaries

change to the bcnu/src directory

review the makefile for your platform if required. Create a new makefile if your platform is not supported.

The likely changes are to the C compiler in use, and the LIBS line for the libraries to be used.

Build the bcnu, bcnud, bcnumsg programs by running:

make

Until it compiles and builds.

N.B. some platforms may generate warnings, if you make any changes please send me an annotated source.

Once it is built you need to add some entries to the makefile at the end to make the distributed binary. see the makefile for details.

Once that’s done the make the distribution version. This creates a binary called bcnu.platform for each of the binaries and makes a symbolic link to this called bcnu.

make platform-dist

bcnuenv.platform

There needs to be a file called bcnuenv.platform e.g. bcnuenv.solaris for the server type, the format is very simple:

#!/bin/sh
# bcnuenv.solaris

BCNUUSER="nobody"
BCNUGROUP="nobody"
PS="/bin/ps -ef"
DF="/bin/df -k"
PING="/usr/sbin/ping"
PINGPAR="" # No. of bytes and # of pings.
MAIL="/usr/ucb/mail -s"
UPTIME="/usr/bin/uptime"
AWK="/usr/bin/nawk"
VMSTAT="/usr/bin/vmstat -S"
VMSTATAWK='{ printf("%d %d %d %d %d %d %d\n",$3,$5,$7,$9,$20,$21,$22) }'
KERMIT="/usr/local/bin/kermit"
GREP="/usr/bin/egrep"
DU="/usr/bin/du -kd"

Once you’ve got a working system you should modify the scripts in /usr/local/bcnu/scripts to add your new platform to the list of supported systems.

There is also a script called get_binaries which you can use to pull the bcnu, bcnud and bcnumsg binaries onto your master host.

Once you’ve got your new platform, run the client_build script to build a distribution for installation on other systems.


Copyright 1999,2000 - John Phillips