Owl Monitoring System Sensor Installation Manual

4. Adding Sensors

	4.1.		Firewall Configuration
	4.2.		SSH Set-up
	4.3.		Get Configuration Data from Manager
	4.4.		Set Up the Owl Configuration File
	4.5.		Test Transfer to Manager
	4.6.		Add Start-up Entries
	4.7.		Add cron Entries
	4.8.		Start Owl Daemons

Whenever a new Owl sensor is added to those handled by an Owl manager, there are a number of actions that must take place on both the sensor and the manager. These actions should be followed consecutively within each section. However, there is some amount of necessary interleaving of sensor actions and manager actions. For example, a particular sensor action may be required before a particular manager action.

It is acceptable for the Owl sensor and Owl manager to be under completely different administrative control. Each host may even be owned by different commercial, educational, governmental, or other such entity. All that is required is that there be some initial coordination between administrators when the sensor is first configured, along with (probably) aperiodic support from time to time later.

The discussions on adding Owl sensors assumes that the sensor and manager are under different administrative control. Required actions will not change if they are under unified administrative control, but they may be easier to accomplish.

This section describes the configuration and testing actions that must be undertaken in order to have a working Owl sensor. It assumes the installation procedures detailed in section 2.1 have been completed.

4.1. Firewall Configuration

The Owl sensor and the Owl manager communicate by way of SSH and HTTP. If the Owl sensor is protected by a firewall (either on the sensor host itself or by an enterprise-level firewall) then the firewall must be configured to allow data to be transferred between the sensor and the manager. The direction of this transfer (initiated by sensor or initiated by manager) depends on the Owl configuration. These firewall modifications are far beyond the scope of this document.

4.2. SSH Set-up

You must generate a new SSH key for the sensor's Owl user.

If the sensor will be transferring data to the manager, then you must provide the public key to the administrator of the Owl manager. This key will allow owl-transfer to pass Owl sensor data to the manager. You must generate keys with key characteristics (e.g., length and type) that are acceptable to the manager's administrator.

If the manager will be pulling data from the sensor, then the manager's administrator must provide you with the manager host's public key. You must add this key to your authorized_keys file. This key will allow owl-transfer-mgr to retrieve Owl sensor data. If you have particular key requirements (e.g., length and type), then you must give them to the manager's administrator.

4.3. Get Configuration Data from Manager

There are several pieces of information that must be provided by the administrator of the Owl manager. These include values for the sensor's configuration file and the sensor's name.

The following data will allow the sensor to work with the Owl manager as expected. These data are used, in conjunction with the manager keyword, in the sensor's configuration file.

Configuration Field		Purpose		Example
ssh-user		User on Owl manager with which owl-transfer will connect via ssh. This is only required if the sensor will be transferring data to the manager.		sensor-ottawa@owl-manager.example.com
heartbeat		URL to provide "heartbeat" data to manager. This is only required if the sensor will be providing heartbeat data.		http://owl.example.com/cgi-bin/owl-sensor-heartbeat.cgi

In addition to these data, it would be a good idea for you and the manager administrator to agree on a name for the sensor. This is not a hostname, but is a name by which your sensor will be known to the Owl Monitoring System. Name agreement between sensor and manager isn't required, but it will probably make things easier for you both in the long run to refer to the sensor by the same name.

The sensor name can be very generic, such as sensor42, sensor-d, or owl-us-east. It can also be very specific, such as washdc-1600-penn-ave-nw or cheltenham-bldg4. The intent is to provide distinguishing information to the intended audience of the DNS monitoring data. You should use names that easily distinguish sensors and are acceptable to the manager and sensor administrators.

4.4. Set Up the Owl Configuration File

The Owl configuration file must be initialized. The data fields include sensor information, query definitions, file locations, transfer intervals, and information about contacting the manager.

The following is a sample owl.conf file:

	host name rome-sensor
	host sensor-args	-config /home/owl/conf/owl.conf
	host transfer-args	-conf /home/owl/conf/owl.conf
	host admin		owl-mgmt bob@example.com

	query		example.com	d	ns
	query		example.com	d	a
	query		.		h	A
	query		.		m

	data	dir		data
	data	interval	60

	log	dir		log

	remote	ssh-user	owl-mgr@owlmonitor.example.com

	remote	heartbeat	http://owlmonitor.example.com/cgi-bin/owl-sensor-heartbeat.cgi

The full definition of the configuration file may be found in the owl-config.pod manpage.

The sensor configuration file must include a set of query definitions. These are best specified by the administrator of the Owl manager, but you must be willing to generate and transfer the volume of data required by those queries. The impact won't be as large for the sensor as it will be for the manager since the manager is likely to have multiple sensors for which it will store data.

In addition, the manager-contact fields must be set with data provided by the administrator of the Owl manager. The ssh-user field is required for transfer of data files. The heartbeat field is optional, but must be specified if the sensor will provide "heartbeat" information to the manager.

When translated to the configuration file format, the example lines from section 4.3 will look like the following:

	manager ssh-user        sensor-ottawa@owl-manager.example.com
	manager heartbeat	http://owl.example.com/cgi-bin/owl-sensor-heartbeat.cgi

4.5. Test Transfer to Manager

At this point, the manager should be ready to accept data from the Owl sensor. Test that this will succeed with the following steps:

1. Ensure the Owl manager's administrator is ready for this test.
2. Put a file in the data directory -- specified in the data dir field of the configuration file. It doesn't matter what the file's name is nor its contents.
3. Inform the manager's administrator of the name of the file.
4. Run a test transfer in one of these ways:
   • If the sensor will be transferring data to the manager, then run "owl-transfer -config <config-file> -foreground".
     
   • If the manager will be transferring data from the sensor, then the manager's administrator must run the owl-transfer-mgr command.

If the file was successfully transferred, then the Owl sensor is ready to start generating data and providing it to the manager.

If not, you must determine why the file wasn't transferred. owl-transfer uses the rsync and ssh commands to perform the transfer, so problem diagnosis should start with them.

4.6. Add Start-up Entries

As discussed in section 1.1, you must decide whether you will run the Owl sensor using the owl-sensord daemon or if you will run owl-dnstimer and owl-transfer directly. Both methods are acceptable; the first is more robust in the case of problems.

In any event, you must add entries to your operating system's boot process to start the appropriate Owl daemons. This is highly dependent on the operating system, and may involve such things as adding some lines to /etc/rc.local or adding a start-up file to /etc/rc.d/rc2.d.

These lines executing the Owl sensor daemons may look something like this:

        /home/owl/bin/owl-sensord -config /home/owl/bin/conf/owl.conf

        /home/owl/bin/owl-dnstimer -config /home/owl/bin/conf/owl.conf
        /home/owl/bin/owl-transfer -config /home/owl/bin/conf/owl.conf

It is incumbent upon the installer to determine the proper method of Owl start-up and the proper place to set up execution.

4.7. Add cron Entries

The owl-dataarch, owl-archold, and owl-heartbeat programs provide additional services for the Owl Monitoring System. These programs are not required, but they can ease some of the burden of administering an Owl sensor. However, due to the volume of data generated by an Owl sensor, it is strongly advised that owl-dataarch be run.

These programs may be set up as cron jobs. This will remove the necessity for the administrator to run these programs manually, and it will provide regularity to their execution.

owl-dataarch periodically moves sensor data from the data directory to an archive directory. It should be run on a daily basis.

owl-archold will create a compressed tarfile of a month's data that has been previously stored in the archive directory. It should be run on a monthly basis -- but not on the first or second day of the month. If the sensor host is used for much other than as an Owl sensor, then it would be best to run owl-archold whenever the system is normally at "off hours."

owl-heartbeat touches a webpage (specified in the configuration file) and is intended to inform the Owl manager that the sensor is up and running. This may be run as often as desired. The more frequently it's run, the more up-to-date is the information on the Owl manager. The less frequently it's run, the lower the granularity of the sensor-availability information on the manager. Once per minute or hour is probably sufficient for most purposes.

4.8. Start Owl Daemons

Installation and configuration are complete for the Owl sensor. The Owl sensor is now ready to gather timing data on DNS queries. If the sensor will be transferring data to the Owl manager, it is ready for that task as well. To start the Owl sensor daemons, you can either start them manually (either by running just owl-sensord or by running both owl-dnswatch and owl-transfer) or by rebooting your system.