Highwinds Software Product Documentation: Typhoon, Twister, Tornado, Hurricane, and Cyclone
<<< Previous	Chapter 3. Typhoon, Twister, and Tornado Back End Product Documentation	Next >>>

3.4. Operations Guide

The following sections provide a guide to the operation of the Typhoon, Twister, and Tornado Back End.

Standard Operation Starting, restarting, stopping, log files, adding and removing groups, manually cancelling messages, editing configuration files, adding and removing feeds, spam filtering, enterprise-wide article number synchronization, supporting the NEWNEWS command.
Monitoring the System Descriptions of syslog and other system information.
Emergency Guide What to do when the unexpected happens.

3.4.1. Standard Operation

In the bin directory, you will find the start, stop, restart, and statsnow command scripts. These scripts control the <typhoond|twisterd|tornado_be> binary contained in that directory. By default, Typhoon, Twister, and Tornado Back End should be started by having the "root" user run the start command script.

Typhoon, Twister, and Tornado Back End will bind to the privileged NNTP port (119) and Twister and Tornado Back End will bind the the default HTTP port (80). After startup the process will change to the user "news" (Typhoon, Twister, and Tornado Back End will refuse to continue if they cannot relinquish "root" privileges). You can easily modify the way Highwinds Software products operate by modifying these command scripts. Every Highwinds Software binary provides the -help option which explains program options. Additionally, you can view the start option guide.

To stop the system, run bin/stop. To restart the system run bin/restart. To update statistics files immediately run bin/statsnow.

If you wish to have statistics reports "at the top of the hour" (which is exceptionally useful if you wish to process your logs) you can use the -update 0 option to disable statistics and to use a simple cron(1M) job to run the bin/statsnow command script at whatever time interval you desire.

3.4.1.1. Reconfiguring the System

To add or remove a feed object it is necessary to restart the system. To minimize system down time, it makes sense to first edit the feeds.conf file, then run bin/validate to make sure the edits are syntactically correct, and finally run bin/restart to restart the server.

The validate command script can be used to ensure the integrity of the configuration files after editing (try the -detailed option).

	Run-time Feed Reloading
	As of January, 2003, all Highwinds Software products support run-time feed reconfiguration

3.4.1.1.1. Editing Configuration Files

It is very important not to truncate the description, moderators, or authentication files while the system is running. Many text editors will truncate files while saving; this could have undesirable effects. If you wish to edit these files while the system is running, you should:

copy the file to a different name (e.g. cp moderators moderators.new)
edit the copy (e.g. vi moderators.new)
link the current file to a different name (e.g. ln moderators moderators.old)
mv the new file onto the old file (e.g. mv moderators.new moderators)
remove the old file (e.g. rm moderators.old)

To edit the active file while the system is running, use the active.control. Of course, all of these files can be safely edited normally while the system is stopped.

3.4.1.1.2. Run-time reloading of Feed Configurations

Reloading a new feed configuration has often been a hurdle for users of Highwinds Software products. Customers had to use the restart command which disconnects users actively using the server. To solve this problem, the run-time feed configuration reloading was added.

To reload a Feed Configuration (changes to feeds.conf), do the following:
Make the appropriate changes to feeds.conf.
Touch a file (owned by the "news" user or the user defined by the -user start option) named etc/feeds.control.
Run bin/reload.
View the INFO level syslog to verify the success of the reload.

The idea of run-time Feed Configuration reloading is to avoid disconnecting any existing connections. Otherwise, a restart preferable.

After a run-time reload, existing connections continue to use the old feed objects and their associated system memory. As a precaution to prevent older feed objects from accessing forbidden system memory, memory is not freed (malloc(3), free(3)) as it otherwise would be with a restart. Therefore, using run-time feed reloading shouldn't be done unless using bin/restart is not an option. When using run-time feed reloading, keep this in mind and run bin/restart when your system allows.

	Run-time Reloading Availability
	Run-time reloading is not available for <typhoon\|twister\|tornado_be>.conf configuration parameters.

3.4.1.2. Log Files

By adding the -log option to the start command script, Typhoon, Twister, and Tornado Back End will create logfiles containing the article id of every article sent or received. These logfiles can be rotated by renaming them with the UNIX mv(2) command and running the statsnow command script. Highwinds Software recommends against using the -log logfile except when tracking problems or trying to compile detailed statistics.

The logfile will note which spool each article is stored in (see the file etc/README.stats), but will also use special spool names for articles which are dropped. The codes below indicate the reason an article was dropped.

Table 3-3. Typhoon, Twister, and Tornado Back End Spool Codes

Code	Description
0a	None of the groups to which the article was posted was in the active file.
0c	The article was a control message and was not saved either because you do not have the control.* groups in your active file, or because you do not have a spool which specifies "StoreControlMessage true".
0e	The article was not saved due to a configuration error. Check the syslog for a more specific reason.
0f	The article arrived from a remote site and was thrown away by the `-program` or `-postprog` filter.
0i	The article was thrown away by an Incoming limit. For example, MaxCrosspost or IncomingGroupFilter.
0m	The article was posted to a moderated group without approval.
0s	No spool was willing to store the article, due to spool subscription, article size, subject pattern, or control-message limitations.
0x	In XRefAction Parse mode, the article arrived without an XRef header.

3.4.1.3. Rotating Log Files

The logfiles generated by -log, -stats, and -paths are all flushed and re-opened each statistics interval, or whenever bin/statsnow is run. The best way to rotate your logfiles is:

mv logfile logfile.old
run bin/statsnow
sleep 15 (to wait for the file to flush)
do any post-processing, like compression or reports generation

You don't need to "touch" the new logfile.

3.4.1.4. Adding/Removing Groups

To add or remove a group on a running system, you can do one of two things:

Do nothing but send the server a numbered feed so long as XRefAction Parse and AutoAddGroups True are set.
Create a file in the same directory as the active file called active.control. In this file, list the changes you wish to make to the active file.

To remove a group, add a line to active.control consisting of the group name preceded by a dash ('-').

To modify an existing group, add an active file entry line preceded by an equals sign ('=').

To add a group only if it doesn't already exist, preceded a plus ('+') character to the active file entry line. To add a group if it doesn't exist or to modify its bounds if it does, simply place the active file entry line for this group in active.control as you would in the active.

When using the equals sign ('='), specifying zero ('0') for one of the article bounds leaves the existing bound unchanged.

For instance, the following lines would:

Add the group comp.compilers if it didn't already exist.
Adjust the low bounds on the group rec.much.traffic to 10000 if it exists.
Remove the group talk.binary.inane.chatter.
Add or modify the group comp.lang.tcl
Change the moderation status of the group comp.moderated without touching its high and low article bounds.
Add the group comp.lang.java if it didn't already exist ensuring that it is a moderated group.

Example 3-7. active.control example

	+comp.compilers
	=rec.much.traffic 0 10000
	-talk.binary.inane.chatter
	comp.lang.tcl 100 1 y
	=comp.moderated 0 0 m
	+comp.lang.java 0 0 m

After creating the active.control file, tell the server to process the file by running the bin/reload command script.

Adding groups is simple once you have an initial empty active file.

3.4.1.11.1. Creating an Empty Active File

You can use the tools/activeTool command to perform operations to your active file. To create an empty active file, run tools/activeTool -create -filename etc/active. Once you have empty active.names and active.table files, you can add groups.

3.4.2. Monitoring the System

Typhoon, Twister, and Tornado Back End use the UNIX syslog system to report system status. Messages are logged with the LOG_NEWS facility and the severity levels detailed below. By default, most operating systems send LOG_ERR (and higher) severity levels to the system console. Keeping this default is recommended.

If you wish to obtain additional information about the running system, you should add the -detailed option to the start command script. In addition, you should modify your syslog configuration file to record LOG_INFO severity levels.

For reference, an example syslog.conf follows, refer to your UNIX documentation regarding syslog.conf(4) for more details and be sure to send a HUP signal to the syslogd process kill -HUP <syslogd PID>.

	# VERY IMPORTANT these \/ \/ spaces are TABS, not spaces.
	news.alert                  /home/highwinds/log/news.alert
	news.crit                   /home/highwinds/log/news.crit
	news.err                    /home/highwinds/log/news.err
	news.info                   /home/highwinds/log/news.info

Table 3-4. Typhoon, Twister, and Tornado Back End Syslog Severity Levels

Level	Description
LOG_ALERT	This message is sent when an unrecoverable error occurs. This happens when a critical resource outside the control of the system has misbehaved.
LOG_CRIT	This happens when a serious error occurs. The system (in general) will make a best effort to recover from these errors. These types of errors may require intervention.
LOG_ERR	This happens when a normal error occurs. These errors are (in general) recoverable and do not require intervention. However, large numbers of these errors should not be a "normal" situation.
LOG_INFO	This happens when the system finds some information that it believes an observing administrator might find interesting or useful for statistical purposes. To enable these messages, you must run <typhoond\|twisterd\|tornado_be>* with the `-detailed` option.*

3.4.3. Emergency Guide

Turn on Detailed Logging: By adding the -log option, you will see more details of the system's operation. You may wish to use the -log option to log the article ids of every message processed. Be sure to refer to Monitoring the System for more details.
Look at the Statistics: Statistics reports detail article and connection statistics. This data is a great starting point for all debugging. If you are having trouble, you may wish to use the checkpoint and statsnow command scripts to get data out of the system more frequently.
Turn off DNS: If you have an unreliable DNS, modify the bin/start command script to use the -nodns option. This will require you to modify the feeds.conf file to use ONLY numeric IP addresses for all host values. After making the modifications, run the bin/restart command script.

<<< Previous	Home	Next >>>
Configuration Guide	Up	Tornado Configuration Guide