User Guide Version 1.18

The installation process should be painless on one of the supported platforms. A step by step guide follows:

There are a number of scripts which can help when installing bcnu, these are described here

Installing the bcnu master system

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 one of the pre-built executables, go to the section on configuring bcnu for a new platform.

Once bcnu is installed, 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 any maintenance is the agents file.

Configuring bcnu on the master

Decide on the final location of bcnu (/usr/local/bcnu is the default)

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

Run the client install script in bcnu/scripts/client_install to set up the environment.

It will ask for the location of bcnu (e.g. /usr/local/bcnu) and then operating system type.

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

The script will ask if you want bcnu started at startup, if the answer is yes it will add an entry to the appropriate startup file/directory for your platform. (N.B. root access may be required for this).

Once that’s complete change to the directory /usr/local/bcnu/etc

Config files

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

The bcnuenv file will be edited based on the answers to the questions in the install script.

The other files will have all the entries commented out ready to be enabled.

bcnud_server

This is the script that starts bcnud. It should be run whenever the system is started up or shut down.

 

Configuring bcnu clients

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 agents 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 client_install 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.

Testing the installation

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.0.1, started at 1998-03-25 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/ag_av.status

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.

It is now time to edit the agent config file, 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.

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:

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.0.1, started at 1998-03-25 13.49.34, 3 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 status message will be sent after 5 more runs.

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 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 the only agent 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

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

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.

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!)

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.

The av agent is run when the bcnu system starts up or shuts down. It sends a message to the master with the version of the os from the uname command, a copy of the agents file and some more useful info. When the system is shut down the av agent sends a blackout message to the master.

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.

If you have a system which uses disk mirroring on solaris,aix 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.

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.

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/bcnuenv script to change the BCNUURL variable to reference this location e.g.

BCNUURL="/~jap/bcnu"

 

You should also change the /usr/local/bcnu/cgi-bin/bcnu.inc file to specify the url and home directories.

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 "/usr/local/apache/htdocs/bcnu/cgi-bin">

Options ExecCGI

</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/systems.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/systems.htm

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
#
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"

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.