The following sections provide a guide to the operation of the system.

• Standard Operations
  Starting, restarting, stopping, logfiles, statistics, checkpoint messages, active file, group file, the Top 1000, and Multi-Homed machines.

• Monitoring the System
  Descriptions of syslog and other system information.

• A Day in the Life of an Article
  Detailed description of how an article moves through the system.

• Emergency Guide
  What to do when the unexpected happens.

In the bin directory, you will find the start, stop, restart, rotate, and statsnow command scripts. These scripts control the cycloned binary contained in that directory. By default, Cyclone should be started by having the "root" user run the start command script.

Cyclone will bind to the privileged NNTP port and become the user "news" (Cyclone will refuse to continue if it cannot relinquish its "root" privileges). You can easily modify the way Cyclone operates by modifying these command scripts. Every Cyclone binary provides the "-help" option which explains program options.

The validate command script can be used to ensure the integrity of the Cyclone configuration files after editing (try the "-detailed" option). To install a new configuration: Edit the Cyclone configuration files, run validate to check the configuration, and finally run the restart command script to install the new configuration.

Cyclone computes and updates raw statistics files (by default) to the log directory on an hourly basis. You can modify where and when the statistics get updated by using the "-stats" and the "-update" options as well as the statsnow command script. The specific format of Cyclone statistics are documented in the README.stats file.

If instead of a filename, you specify "local0", "local1", ..., or "local7" to the "-stats" option the system will syslog the statistics data to the named facility at LOG_INFO priority.

The quick.pl and summarize.pl PERL scripts produce formatted summaries of Cyclone statistics. These scripts can be run from the command line on both Incoming and Outgoing statistics files. Comments at the top of the summarize.pl script explain a very simple modification that can be made to turn it into a CGI program.

To rotate your statistics files on a daily basis, we recommend setting up a cron(1M) entry to run the rotate command script daily at 12:01AM.

The checkpoint command script, causes Cyclone to syslog connection statistics to the LOG_NEWS facility at LOG_INFO priority. By using this command script, you can obtain instantaneous status information without interfering with normal Cyclone statistics reporting.

You MUST run Cyclone with the "-detailed" option if you wish to use this feature.

Although Cyclone doesn't need an "Active File", by providing a filename to the "-active" option of cycloned, you can limit the articles that you receive to the Newsgroups listed in the specified file.

The Active File should contain one Newsgroup per line (Cyclone accepts active files from other news systems). For example:

comp.lang.tcl 0000000001 0000000000 y
comp.lang.c.moderated 0000007595 0000007577 m

If you provide an Active File, any article not posted to at least one Newsgroup listed in the file will be treated as "junk" and will not be sent to an outgoing feed unless that feed has the AllowJunk directive set to "Yes".

You can use the XrefAction directive in the cyclone.conf file along with an Active file to Generate Xref: header lines. This is an easy way to allow downstream News Systems to synchronize article numbers by simply parsing the Xref: header line.

Finally, if your active file specifies that a specific group should be "moderated" and the DropUnapprovedArticles directive is set to "True", any articles appearing in those groups that do not have an Approved: header line will not be propogated.

By providing a filename to the "-groups" option of cycloned, Cyclone will tabulate and save Incoming Newsgroup statistics to the specified file. With this option, you can accurately track the number of articles, size, and crosspostings of each Newsgroup you receive from peer systems. Because these statistics are calculated BEFORE any articles are eliminated, you can use the Group File to see what new Newsgroups you might want to begin carrying or filtering.

Keep in mind that Cyclone will read and update the existing copy of the incoming Newsgroup statistics whenever the statistics are updated.

The groupstats.pl PERL script can produce both regular and HTML formatted summaries of the Group File. This script can be run from the command line or as a CGI program from a Web Server. Comments at the top of the script explain a very simple modification that can be made to turn it into a CGI program.

The very generous folks at Freenix provide a monthly service that tracks the "Top 1000" sites on USENET. As a part of this service, they provide the source code to a program you can use to prepare data from your site for submission to their service.

To send your contribution to the USENET Top 1000, visit the Top 1000 site at http://www.freenix.fr/top1000/, download and compile their "inpaths.c" program, and add the -paths ../log/paths option to cycloned inside the start command script. This option instructs Cyclone to save the Path: field of every message it routes to the argument filename.

Once a month, use the UNIX mv(2) command to move ../log/paths aside and run the bin/restart command script. Finally, run the compiled Freenix program (with the "-p" option) against the saved ../log/paths file and mail the results off to Freenix ("pathsurvey@pathsurvey.eu.org").

HighWind Software is committed to submitting ACCURATE Top 1000 reports. If for any reason you think your Cyclone data is inaccurate, immediately contact us at HighWind Support.

By adding the "-log" option to the start command script, Cyclone 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 restart command script. Since Cyclone provides system status information in other ways, we recommend against using logfiles.

For incoming feeds, adding the "-interface" option to cycloned inside the start command script, will instruct Cyclone to listen on a specific local interface for incoming connections.

For outgoing feeds, you can use the OutgoingInterface directive to select among local interfaces.

Cyclone uses the UNIX syslog system to report system status. Cyclone logs all system alerts 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. Refer to your UNIX documentation regarding syslog.conf(4) for more details.

What follows is a high level summary of the path an article takes through Cyclone. It is meant to give you a brief look into some of the things Cyclone does while processing articles.

• First Contact - A peer system opens a TCP connection to the local NNTP port. This connection is accepted by cycloned if there is an IncomingHostName entry for the peer host in the feeds.conf file.

• Article Transmission - The peer system sends an article to the local system using either normal or streaming NNTP. cycloned checks the history database (bin/history) to see if it has seen the article before. If not, the article is accepted by the local system.

• Parsing and Saving - The article is parsed and checked to ensure that the required header lines are intact and that the article's date stamp is recent. The Path: header line is prepended with the name of the local host (or the names given by the "-masquerade" and "-alias" options to cycloned). The article is then saved into one of the spool's specified in the cyclone.conf file.

• Distribution - After saving the article, cycloned checks it against each feed which has an OutgoingHostName entry. If the article meets all the qualifications of the outgoing feed, an entry is made in a file in a subdirectory of the spool directory named after the OutgoingFeedName of that feed.

• Re-Transmission - cycloned processes the articles stored in the outgoing queues by opening up a connection to the port and host specified by the PortNumber and OutgoingHostName entries for each of the feeds. cycloned sends the article to the remote host and the cycle repeats.

HighWind has worked extremely hard to make Cyclone the most reliable and worry-free news system possible. However, lots of things can go wrong that are not within Cyclone's control.

• Turn On Detailed Messages - By adding the "-detailed" option, you will see more details of the system's operation. You may wish to use the "-log" option to have Cyclone 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 and Checkpoints 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.

Back to Cyclone Documentation