** Documentation for CHANGI 0.9 ** June 15th, 1995 ==================================================================== Changi The meaning of... ==================================================================== Why is this called Changi? What does Changi mean? Where does this name came from? Since (almost) nobody was really interested to get an answer on these essential questions, I won't tell you. At least you should be able to pronounce it correctly. Ch like ch in children a like o in love ng like ng in ringing i like i in rings What's this crap for? --------------------- Changi is a NNTP server for OS/2. In fact it is a set of programs to enable you reading and writing newsgroup articles using your favourite NNTP newsreader (NR/2, TIN and others) on a single machine or in a local TCP/IP network. You may also use it to query new articles from your NNTP newsfeed, read them offline, post new articles offline and send them to your newsfeed at a later time. If you prefer UUCP to exchange news with the outer world, you may use UUPC for OS/2, to which Changi is fully compatible. Legal stuff ----------- Permission is granted to any individual or institution to use, copy, or redistribute this executable so long as it is not sold for profit. However, this may not apply to any part of source code. LIKE ANYTHING ELSE THAT'S FREE, CHANGI AND ITS ASSOCIATED UTILITIES ARE PROVIDED AS IS AND COME WITH NO WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED. This is the first release of a NNTP daemon for OS/2. It is a quick and dirty port of NNTP 1.5.11t5. Therefore credits should go to it's authors, Phil Lapsley, Stan Barber and others. Parts of the Changi distribution are copyright by Kendra Electronic. Other parts were stolen from code written by Kai Uwe Rommel. Hey, wait! Nothing is really free...today. If you like Changi, send me a postcard with a picture of your hometown. A single postcard can make my day, you know. It will also keep my motivation high to put more effort in a possible refinement of this program. Send your postcard to Harald Kipp Luetgendortmunder Str. 50 44388 Dortmund Germany THERE MAY BE ONLY TWO REASONS FOR NOT SENDING A POSTCARD. 1. YOU DO NOT HAVE THE MONEY TO BUY THE STAMPS. 2. THERE IS NO POST OFFICE NEAR (100 KILOMETERS) YOUR PLACE. (Yes, there is one at the northpole.) With version 0.5 I received postcards from Alex (Surrey, UK) Bill (one from NY, the other from Dallas) Harold (Montreal) John (SF, near Germany) Five cards from four people is not bad, if you consider the difficulties of an email and newsgroup freak to find out about postcards, stamps and post offices. Obtaining the latest version ---------------------------- Every new version will be sent to ftp.hobbes.nmsu.edu and announced in comp.os.os2.networking.tcp-ip. Changi Getting help ==================================================================== Please send flames, suggestions, bug reports for this modified version to: Internet: harald@os2point.ping.de (home) harald@sesam.com (office) Fido: 2:2448/434 (home) 2:2448/404 (office) Both internet links are not very reliable, while the Fido nodes might not be checked daily. If you cannot reach me at one address, try another. English is not my native language, but I'm interested to improve it. Don't hesitate to tell me about grammatical mistakes or other bad linguistic use in this document. Where to find help too ---------------------- The author and other people a frequently checking the newsgroup comp.os.os2.networking.tcp-ip for discussions related to Changi. Before posting your problems or suggestions to this newsgroup remember that Usenet is a volunteer network. All the code, maintenance, and answering are done by people who freely give their time to help the net. Please consider this and treat them accordingly. Be as precise as possible so that overworked knowledgeable people will not waste time trying to solve the wrong problem. Do not post articles to this group, which are not directly connected to OS/2, TCP/IP and their related tools. For general questions about Usenet you might look into the following newsgroups: news.admin.misc General topics of network news administration. news.admin.policy Policy issues of Usenet. news.admin.technical Maintaining network news. (Moderated) news.software.b Discussion about B-news-compatible software. news.software.nn Discussion about the "nn" news reader package. news.software.nntp The Network News Transfer Protocol. news.software.readers Software used to read network news. news.sysadmin Comments directed to system administrators. news.announce.newusers Explanatory postings for new users. news.newusers.questions Q & A for users new to the Usenet. Changi Upgrading ==================================================================== This version contains many changes to the previous release 0.5. And it contains even more bug fixes, but due to the many changes new bugs may have been included too. The environment variable NEWSSERVER is no longer used. Programs in this package will now read the variable named NNTPSERVER instead. You may use either slashes or backslashes to specify directory paths, but backslashes are now the preferred method to avoid trouble with 4OS2. There a three new programs included. One is called Chanco which will handle control messages. Another is called Shrink and may be applied to your ever growing logfiles. And at least I added the long missing Expire to keep your newsbase tidy. Many programs in this package got many new options. For a quick start you may simply copy all binaries of this new version to your CHANGIWORKDIR and enter the NNTPSERVER environment setting into your config.sys. At least check your changi.cfg against the one included here for new items. Other changes ------------- I didn't understand the implementation of xover for a long time and didn't fully implement it in the current version. But at least Changi is now faking it. Code in the logfile module has been cleaned up. At least the most important logging of NNTP telegrams is working now. The IHAVE protocol has been implemented. Unfortunately I can't test it. The server wasn't drive aware. All directories had to reside on the same drive. This had been fixed. A new configuration file item 'access' may be used to limit access rights of other hosts on Changi. Added support for active.times, so NEWGROUPS should work now. A new configuration item 'actimes' specifies the path to this file. Changi Package ==================================================================== The Changi distribution is divided into several different programs to provide high flexibility, compatibility with other news processing software and easy expandability. CHANGI.EXE The NNTP server program is running permanently in the background. Best place to start it will be the tcpexit.cmd. CHANX.EXE This is a NNTP client used to transfer news articles between the newsbase on your local machine and a NNTP server on a remote host. INEWS.EXE This program is called by Changi whenever a connected client is posting in article. Inews will store the article in the spool directory for later transfer by chanx and it will call Rnews. RNEWS.EXE Called by Inews and Chanx (and even Changi in special cases) this program stores an article in the local newsbase. If the article contains a control message, Rnews will call Chanco. CHANCO.EXE !!! NEW !!! This program may be called from the command line to create new or remove outdated newsgroups. When called by Rnews it is also used to cancel news articles. EXPIRE.EXE !!! NEW !!! You should call this program once a day to keep your local newsbase tidy. Expire may also be used to recreate your history file. SHRINK.EXE !!! NEW !!! All programs in the Changi distribution will create ever growing log files. Use this program to shrink them to a specified size. For your convenience a sample CHANGI.CFG is included. Use any text editor to modify this file to meet your needs. Changi Installation ==================================================================== You need OS/2 but you don't need Warp. Any version including 1.3 or above should be sufficient. Changi needs HPFS. It will not work on FAT formatted drives. You need either IBM TCP/IP for OS/2 (base kit version 1.2.1 or above) or WARP IAK. How to install? --------------- Create a new directory, copy the Changi archive into it and unpack it. Edit your config.sys to add a new environment variable named CHANGIWORKDIR which points to the directory where you unpacked Changi. For example, if you put Changi into C:\Changi then you must add SET CHANGIWORKDIR=C:\Changi to your config.sys. In addition Changi will use the following environment, if set: SET TMP= SET NNTPSERVER= SET HOSTNAME= Under any circumstances, you need at least take a look at or create and/or edit the following files that all should be in your %CHANGIWORKDIR% directory, if not otherwise specified. changi.cfg - the global configuration file active - the active file Changi operates via TCP/IP at the port indicated in the 'nntp' service entry in a file named services. Make sure that the following line exists in your etc\services file: nntp 119/tcp Edit changi.cfg to meet your needs. This file contains lots of comments to help you choosing the correct settings. You must also create a simple text file in the CHANGIWORKDIR named active. This file must contain all newsgroup names you wish to read from or write to, one per line with some extra information. The format of this file is described in detail in one of the following chapters. If you haven't installed the TCP/IP base kit and want to run the server on a machine with IAK only without being connected to the net, run the following command before starting Changi. ifconfig lo 127.0.0.1 You may now refer to your machine using this ip-address. For example you may start NR/2 with nr2 127.0.0.1 Reboot your computer to make your changes in the config.sys working. Change to the Changi directory and start Changi.exe. Start nr2.exe (part of the IAK) with your IP address (setup with ifconfig) as a command line parameter. Changi Configuration ==================================================================== All programs in this package get their configuration from three sources. They read the contents of specific enironment variables, read the contents of a configuration file usually named changi.cfg and they read their command line parameters. Command line parameters may overwrite settings in the configuration file, while these may overwrite environment settings. Environment variables --------------------- SET CHANGIWORKDIR= This specifies the home (or root) directory for Changi. Any reference to a file or directory given without an absolute path will be assumed to live in this directory. Although this parameter is optional it should be specified. If not given, the current directory is used. SET TMP= Specifies a directory to be used for temporary files. This may point to a RAM-disk, although I won't recommend it. At least one hole article must fit in this directory. Be aware that other programs may use this too and it is not a good idea to run OS/2 with a huge RAM-disk. This parameter is optional, if not defined Changi will use the current directory. SET HOSTNAME= Specifies the full domain name of your local host. If you don't define this parameter you must include the MyDomain item in the configuration file. SET NNTPSERVER= Specifies either the simple hostname or the full domain name of your remote host. If you don't define this parameter you must include the Newsserver item in the configuration file. Configuration file ------------------ The programs of the Changi distribution will by default read additional configuration options from the file changi.cfg. This file is read on a line by line basis. Lines starting with a '#' (number sign) are treated as comments and are ignored. Empty line are allowed to increase readability. Configuration lines are specified by a keyword followed by one or more spaces and/or tabs and a specific parameter. All keywords are case insensitive. This file might be read by all programs of the Changi distribution. However, not every program uses each parameter. Defining nodenames in the configuration file -------------------------------------------- MYDOMAIN Full domain name of your local host on which Changi is running. If you do not specify this item then you must set the HOSTNAME environment variable with the full domain name. MYNODE Node name of your local host on which Changi is running. If you do not specify this name then Changi will use the beginning of the full domain name up to the first dot character. NEWSSERVER You may either give the name of your news feed here or set the NNTPSERVER environment variable. You should not append any domain information unless your local host and this remote host are in different domains. Defining directories in the configuration file ---------------------------------------------- You may either specify a single directory name without any path or you may otherwise give the full pathname. Under no circumstances partial (relative) directory paths are acceptable. If you supply the name of a single directory then the program will build a full path by appending that name to the value of the CHANGIWORKDIR environment variable. NEWSDIR All articles will be stored in subdirectories below this point. If this directory does not exist, the program will create it for you. Default is 'news'. SPOOLDIR All outgoing articles will be stored in this directory. Default is 'spool'. Defining filenames in the configuration file -------------------------------------------- Like with directories you may either specify the filename without any path or with it's full pathname. If no path is given then the program expects that file in the directory given by the contents of the CHANGIWORKDIR environment variable. ACCESS This optional parameter defines a file containing access restrictions to your NNTP server. ACTIMES An optional parameter specifying the name of a file, which contains a list of new created newsgroups. By default 'active.times' will be used. Changi will create this file automatically if a new newsgroup is created. ACTIVE This optional parameter specifies the name of a file, which contains a list of all active newsgroups. By default Changi will assume a file named 'active' in the CHANGIWORKDIR. This file must exist. HISTORY This parameter overwrites the name of your history file. You should not specify an extension. By default Changi will assume 'history' in the CHANGIWORKDIR and create the two files 'history.pag' and 'history.dir' while news are coming in. Defining special newsgroups in the configuration file ----------------------------------------------------- DUPEGROUP Name of the newsgroup where Changi will store received duplicate articles. The name 'duplicates' will be used if this parameter isn't defined. If the specified group does not exist in the active file, duplicate articles are junked. JUNKGROUP Name of the newsgroup to store junked articles. Default is 'junk'. If the specified group doesn't exist in the active file, junked articles are discarded. Defining program calls in the configuration file ------------------------------------------------ If you specify the name of the program without path then that program must reside in one of the directories given by your PATH environment variable. Otherwise you must give it's full pathname. CONTROL Specifies the command line to be called if control messages are received. By default 'chanco' will be called, which is part of the Changi distribution. GUNZIP Specifies the pathname of a program to be used to uncompress zipped batchfiles. If not defined, then 'gzip -d' will be used. You won't need to define this parameter unless you are using UUCP to transfer your news, because Changi itself will never create compressed batches. The gzip program is not part of the changi distribution. INEWS Overwrites the command line which Changi will use to inject news articles to the net. By default Changi will call 'inews' without any command line parameters. The inews program is part of the Changi distribution. However, you are free to use a similar program from other sources. RNEWS Defines the command line which Changi will use to store news articles in the local newsbase. By default Changi will call 'rnews' without any command line options. The rnews program is part of the Changi distribution. However, you are free to use a similar program from other sources. UNCOMPRESS This program will only be used if rnews must process compressed batches which had been received by UUCP. If you don't know what this might be good for then you won't need it. Default is 'uncompre'. This program is not part of the Changi distirbution. Changi File formats ==================================================================== This chapter provides a list of data files used by the Changi distribution. It explains contents and usage of these files. active ------ This file must contain all newsgroup names you wish to read from or write to, one per line, including current maximum and minimum article numbers and moderation status. You can use any text editor to create this file. Note, that the current version of Changi can only handle active files with a maximum size of 32 kByte. Here is an example line These may be spaces or tabs v v v comp.os.os2.networking.tcp-ip 0 1 y ^ ^ ^ ^ Name of the newsgroup ^ ^ ^ ^ ^ ^ Highest article number ^ ^ initially 0 ^ ^ ^ ^ Lowest article number ^ initially 1 ^ ^ Means yes, you may post to this group use n to prohibit posting (read only) use m for moderated groups After receiving articles for a while the line might look like this: comp.os.os2.networking.tcp-ip 10929 8732 y With this line and the configuration Changi expects articles in the files %CHANGIWORKDIR%\news\comp\os\os2\networking\tcp-ip\8732 up to %CHANGIWORKDIR%\news\comp\os\os2\networking\tcp-ip\10929 After the initial creation of this file you should use Chanco to create new newsgroups. active.old ---------- Backup of the previous active file created by Changi when modifying the original. history ------- This files contains a list of articles currently known at this site, with reception date, article size and pathname. By default Changi will assume 'history' in the CHANGIWORKDIR. It will automatically create two files while news are coming in. One is named 'history.dir' and contains an index to the second one named 'history.pag', which is a simple text file. Here is an example line of my history.pag file: This must be a colon v These MUST be spaces (no tabs!) v v v v v <5d1L8YlGGiB@cat.ping.de> 789107022 939 comp.os.os2.setup:12235 ^ ^ ^ ^ ^ Message-id ^ ^ ^ ^ ^ ^ ^ ^ Time at which article ^ ^ ^ was received (seconds) ^ ^ ^ ^ ^ ^ Lines in the article ^ ^ ^ ^ This is the name of the newsgroup ^ ^ This is the number of the article First a connected newsreader may asks Changi for all ids of a specified newsgroup received after a specified time. The time is used to maintain the number of unread articles and is given in seconds since 01/01/1970. For example, when NR/2 starts for the very first time it will ask for all articles since 01/01/1986. To retrieve the article of our example line, the newsreader will query for <5d1L8YlGGiB@cat.ping.de> and Changi tries to find a line in the history file with this id at the beginning. In our example the article itself will exist in %CHANGIWORKDIR%\news\comp\os\os2\setup\12235 If your history files get lost or corrupted you can use Expire to recreate it. SEQF ---- This file is created and maintained by Inews and contains a simple number. This number will be used for creating job-ids. The local time in seconds since 01/01/1970 will be used too, but because it is possible that more than one spool job might be created within a single second, Changi uses this extra counter. It is incremented with each spool job. active.times ------------ Chanco will create and maintain this file if new newsgroups are created. It contains a list of created newsgroups and the time they were created, aimed at making it possible for news readers to be smarter about knowing when a group is new. newsgroups ---------- List of know newsgroups and descriptions. Each line contains a group name, a tab, and a terse description of the group. The descriptions are read only by humans. You may either create this file with your text editor or use Chanx to retrieve a list from your news feed. Spool files ----------- After posting an article to, let's say lilly, Inews will create spool\lilly\C\ spool\lilly\D\ if called with option '-U', or spool\C.lilly spool\D.lilly if called without this option. ==================================================================== Changi Daemon Command line options ==================================================================== While the previous chapter was dealing with those configuration items used by all programs of the Changi distribution, the following information is specific to changi.exe only. Some of these options may be used to overwrite definitions made in the configuration file. -? The program will display a usage help and stop immediately. -a Overwrites the name of the active file. -c Sets the name of the configuration file. By default 'changi.cfg' will be used. -da Logs active file handling for debugging. -dd Logs history file handling for debugging. -df Enables log file flushing. Should be specified for debugging only because this might dramatically increase your system load. -dr Logs all NNTP telegrams received from the remote host. Used for debugging. -ds Logs all NNTP telegrams sent to the remote host. Used for debugging. -i Overwrites the command line to inject news into the net. -n Overwrites the name of your local news directoy. -r Overwrites the command line to store news received from the net. Changi uses this parameter if news are received with the IHAVE protocol. -y Overwrites the name of the history file. Changi Daemon Configuring access permissions ==================================================================== You may choose to limit the hosts that can query the server for news. Further, you may not wish to allow certain hosts to post news. Finally, you may wish to restrict the newsgroups that can be accessed from remote hosts. Such limiting can be accomplished through an access file, usually named 'nntp_access'. To do so, define an access entry in your changi.cfg and create 'nntp_access' with your text editor. If you are using Changi as a simple offline newsreader, then there is no need to bother with this file. However, if you keep Changi running while being connected to any net, either a local LAN or the Internet via modem, you should limit access for foreign hosts. This file consists of several lines with three or four fields separated by spaces in the each line. Anything to the right of a '#' (number sign) character is taken to be a comment and is ignored. The absence of an entry corresponding to a client's host or domain implies that the client is not allowed to read or post news. Changi is selective and searches for a best match when searching this file to check its client's permissions. That is, a specific host name match is used over a client being a member of a specified domain. General format of nntp_access ----------------------------- Every entry must have the following format: host|*.domain|default read|xfer|both|no post|no [newsgroups] host|*.domain This may be any valid host name, host address in the dotted decimal form or any valid domain part of a hostname preceeded by an asterisk. Default permissions can be set by having the first entry in the file be a host name of 'default'. If used, 'default' must be the first entry. read|xfer|both|no The second field of the entry specifies the read access of the host in question. read Hosts can read news. This means that all commands except IHAVE and POST can be executed. xfer Matching hosts can only execute commands used for transferring news, such as NEWNEWS, NEWGROUPS, IHAVE, and ARTICLE with message-id parameters. both These host can execute all commands but POST. no This string denies read permission of any kind to a matching host. post|no The third field defines whether a matching host has post permission. post The POST command is permitted no Matching clients are not allowed to post news. newsgroups This field is optional, and, if present, is a comma separated list of newsgroup names that restrict the client's reading ability. Clients are not allowed to read or transfer articles in newsgroup names preceded by an exclamation point. By default, clients are allowed to read all newsgroups. Sample nntp_access ------------------ # # Comments are preceded by '#' # default no no naxos read post dumbgate xfer no comp.os.os2* *.ping.de read no !sesam* Clients on naxos may freely read an post articles, while dumbgate is only allowed to transfer news of the group comp.os.os2 and all it's subgroups. Other hosts in the domain ping.de might read any group except those starting with sesam. The rest of the world isn't granted any access at all. Changi Daemon Operation ==================================================================== The server handles clients on a multithreaded basis, creating threads to take care of clients as they request connections. Each thread changes its current directory to the news directory and then executes commands from its client. The standard commands are described in RFC 977, which differs from the Changi implementation in the following way. SLAVE This command is not implemented. XHDR header [|articlerange] This is a common extension used by many newsreaders to retrieve certain header lines. XOVER [range] This also is a common extension. It returns overview data for the specified range of messages. The default is to return the data for the current article. Bugs ---- Supporting no locking mechanism is one of the major drawbacks of the current implementation. To avoid any file access conflicts you should ensure, that all clients are disconnected while receiving news by Chanx or UUPC or while running Expire. Changi can only be stopped by pressing Ctrl+C. If clients were connected while stopping the program, Changi can't be restarted unless all clients have been disconnected. This is because TCP/IP has a very long timeout on socket connections when the server dies. Changi does not support real XOVER mechanism, but a fake only. Changi has no provision in the current version to send articles with the IHAVE protocol. ==================================================================== Chanx Passive NNTP client ==================================================================== Chanx is a small passive client to send news articles to and retrieve from a remote NNTP server. After establishing a connecting it will send locally posted articles to a remote server and retrieve new articles of a specified set of newsgroups that have arrived after a particular time, which usually is the last time it was invoked. Chanx features -------------- - Compatible with most NNTP servers. From the server point of view Chanx behaves like a typical newsreader. - Several options may significantly decrease article transfer times. - An unlimited number of newsgroups can be retrieved in a single session. - Chanx can read .newsrc for a list of newsgroups to retrieve. - Chanx will use date and time of the remote host to avoid article loss due to unsynchronized clocks. - In case of lost connections Chanx will provides several methods for recovery. Chanx Command line options ==================================================================== Simply call the program without any options to get a usage help: Usage: chanx [options] host [groups YYMMDD HHMMSS [dist]] -c sets the name of the configuration file. By default Chanx will use changi.cfg. -df Enables log file flushing. Should be specified for debugging only because this might dramatically increase your system load. -dr logs all NNTP telegrams sent by the remote host. -ds logs all NNTP telegrams sent to the remote host. -k sets maximum number of k-bytes of articles to retrieve from the remote host. Chanx will check for this limit each time before retrieving an article. -mb (batch mode) will not directly store retrieved articles into the newsbase but creates a temporary file named batch.. This option might decrease the connection time while using large amounts of diskspace. -mc (continuation mode) retrieves articles which ids had been collected in a previous session. In this mode chanx will neither post nor query new articles. -me (enhanced mode) will use an enhanced mode during article retrieval, which may significantly speed up article transfer. Of course this will put an extra load on the remote host. -mi (ignore previous) ignores article ids collected in a previous session. -mn retrieves the current newsgroups list from the server. -mo (omit update) will not update nntp.hostname. By default Chanx updates this file after retrieving the ids of all new articles from the server. -mp (post only) disables the retrieval of new news. -mq (query only) stops Chanx from posting. -mr will send 'MODE READER' to the server. This should be used with INN running on the remote site if it needs to be switched from innd to nnrpd in order to talk to passive clients. -ms will send a 'SLAVE' command to the server. Some NNTP servers might increase the priority for the current session. -p specifies a different port number. By default Chanx uses the nntp entry in etc\services or port 119 if no entry was found. -r overwrites the rnewscall configuration item. -s overwrites the spooldir configuration item. Chanx will check this directory for waiting posts. -t sets maximum connection time in minutes. Note that this function will only work as long as the remote host is sending data. Chanx will check for this limit each time before retrieving an article. Situations in which the server on the remote host stops responding while keeping the connection alive must be handled somewhere else (slip/modem timeout etc.). -y overwrites the historyfile configuration item. host is the hostname of the remote site. This parameter must be specified. groups is a list of the newsgroups you want to request for new articles. Seperate them with a comma. You may use the star character at the end of a newsgroupname as a joker. As an alternative you may use a full specified path to a newsrc file containing the newsgroups you want to retrieve. This file should contain one newsgroup per line, each followed by a colon. Chanx will ignore anything following the colon and it will not modify or update this file in any way. YYMMDD HHMMSS specifies date and time in GMT, not your local time. All articles, which have arrived at the server after this time will be retrieved. dist will only query articles with this distribution. This item is only included for completeness. It may put heavy loads on the server and substantially increase the transfer time. I'll give you an example. chanx sehost.sesam.com comp.os.os2*,alt* 950202 000000 will query the server sehost.sesam.com for all articles of newsgroups beginning with comp.os.os2 and alt which had been received by this server since 02/02/95. If you don't specify the groups then you cannot specify date and time. Default for the groups parameter is *, which means all newsgroups available on that server. Default time is 000000 and default date is the current day. However, all defaults apply only to your first connect with the specified server. After that Chanx will store the name of the newsgroups and the time of the last request in a file named nntp.hostname. Next time you simply enter chanx host Chanx will only retrieve those articles which have been received by the remote server after the time of your last query. You are free to edit the nntp.host file in order to change your list of newsgroups or the date of your last request. The file is a simple textfile containing one single line with three fields speparated by blanks. groups date time Remember that all newsgroups you want to read later on must be defined in your active file. If you've posted articles to a newsgroup then Chanx will send them to your feet automatically before querying new ones. Chanx Operation ==================================================================== Chanx will first get the newsgroup list, distribution list and the start time for the specified server, either from the nntp.host file or from command line options. The program will then connect to the NNTP server at the specified host. With option -mr a 'MODE READER' command and with option -ms a 'SLAVE' command will be sent to the server. Now Chanx issues a 'NEWNEWS' command, asking for all new articles that have arrived within a list of newsgroups after a specified time. The server responds to this with a list of article identifers, which will be stored by Chanx in a file named iwant.host. However, each id will be checked before storage to avoid dupes. Only ids not found in the local history file will be accepted. If the list of newsgroups is too large to fit in a single NNTP standard line (512 bytes maximum), then Chanx will repeat the 'NEWNEWS' command until all newsgroups have been requested. After this Chanx starts retrieving the article for each id of the list in file iwant.host. Depending on option ??? Chanx will either add these articles to a file named batch.host or directly feed them to the rnews program. Return codes ------------ Chanx return codes will be useful to control program flow in batch files. 0 Completed successful 1 Completed successful, but no articles received 2 Configuration error or incorrect arguments 3 General system error 4 Unable to connect to remote host 5 NNTP protocol error Chanx known bugs ---------------- Beside the lack of any locking mechanism, no bugs so far, which probably means that there are lots of bugs to be discovered. ==================================================================== Chanco Control message processor ==================================================================== Chanco is called by Rnews upon receiving a control message. In addition the program may be called from the command line in order to create new or remove outdated newsgroups. Control messages are ordinary-looking news articles which contain a special header line: Control: Such articles are filed in the pseudo-newsgroup control and cause Rnews to call Chanco to perform related actions. Return codes ------------ Chanco return codes might be useful to control program flow in batch files. 0 Completed successful 2 Configuration error or incorrect arguments 3 General system error Chanco known bugs ------------------ Chanco doesn't support any locking mechanism. The program is not very well tested. Options -da and -dh don't work. Chanco Command line options ==================================================================== Calling the program with '-?' option will display a usage help: usage: chanco [options] commands: cancel newgroup rmgroup options: -a active file -c config file -d logfile flags -n news directory -y history file logfile flags: a active file processing f flush logfile after each line h history file processing -c sets the name of the configuration file. By default Chanco will use changi.cfg. -da logs active file modifications. -df Enables log file flushing. Should be specified for debugging only because this might dramatically increase your system load. -dh logs history file modifications. -n overwrites the newsdir configuration item. Chanco needs this parameter to perform the cancel command. -y overwrites the historyfile configuration item. ==================================================================== Inews Inject News ==================================================================== Inews is used to store your postings in the spool directory for later distribution (either by Chanx or UUPC). It reads a Usenet news article (perhaps with headers) from a file or standard input if no file is given, adds some headers and performs some consistency checks. If the article does not meet these checks (for example, posting to non-existent newsgroups) then the article is rejected. If it passes these checks, Inews stores to article together with to special control files in the spool directory for distribution. In the standard mode of operation, Inews calls Rnews to add the article to the local newsbase too. However, newsgroups that start with the six characters 'local.' will not be spooled to other hosts. Several headers may be specified on the command line. Inews exits with a zero status if the article was succesfully posted or mailed, or with a non-zero status if the article could not be delivered. Testing Inews ------------- Testing Inews is quite easy. Create a file named test.art containing something like (excluding the snip lines): ------------------- snip ---------------------- Newsgroups: alt.test From: me@frog.pizza.com Subject: Testing Reply-To: nobody@in.particular This is a test ------------------- snip ---------------------- After saving this file call Inews from the OS/2 command line. inews < test.art What are the 'local.*' newsgroups for? -------------------------------------- The local newsgroups (all newsgroups starting with local) provide a simple way to create groups, which will not be posted to the outside world. Bugs ---- Many command line option still don't work. Inews Command line options ==================================================================== Remember that all options with an attached parameter will accept a single parameter only. If you need a value with more than one word then quotes must be used to prevent inews from splitting them into multiple parameters. -A Overwrite/adds an approval line. This is a potentially dangerous option but at least needed for writing to one specific newsgroup starting with alt (hint, hint, hint). Anyway, don't fiddle around with this unless you really need it. -c Sets the name of the configuration file. By default Inews will use changi.cfg. -C This option is used to create new newsgroups. Not implemented. Use Chanco to create new groups. -df Enables log file flushing. Should be specified for debugging only because this might dramatically increase your system load. -d Option '-df' is the only one currently working. -D This option allows you to specify the maximum geographic distribution of any post. -e This will override the default expiration date. -f This option specifies the article's sender. -F This option is used to attach a list of related articles which this message references to. -g Specifies the grade for spooling articles to UUCP. -h ignored, but added for compatibility -M This flag is used for the creation of newsgroups. Not implemented. Use Chanco to create new groups. -N To submit an article to multiple newsgroups, the list must be separated by commas. -o This options is used to specify organization name. -r This parameter specifies the 'Reply-To:' line in the article header. -s Specifies the spool directory. -S Not implemented. -t Overwrites the 'Subject:' line in the article header. -U This option will force Inews to use the UUPC mangling mechanism for the spool file names. Do not set this option if you are using Chanx to transfer your locally posted articles to a remote host. -v Verbose, prints ids. Not implemented. ==================================================================== Rnews Receiving news ==================================================================== Rnews reads messages sent by a newsfeed and stores them in the local newsbase. The message is read from the specified input file, or standard input if no input is named. When sent over UUCP, Usenet articles are typically joined in a single file called batch file, to reduce the UUCP overhead. Batches can also be compressed, to reduce the communication time. If a message does not start with a number sign (``#'') and an exclamation point, then the entire input is taken as a single news article. If it does start with with those two characters, then the first line is read and interpreted as a batch command. What's the 'junk' newsgroup for? -------------------------------- The junk newsgroup contains all the articles which rnews couldn't file under a newsgroup name. These can include malformed postings, postings to bogus groups, postings to groups that have been deleted, postings to new groups that you haven't added yet, and postings to groups that you don't carry at your site, and don't intend to. Bugs ---- Looks like Inews is not creating the spool directory. You should create it manually. Missing security checks and configuration on control messages. Many command line options are not implemented. Rnews Command line options ==================================================================== Remember that all options with an attached parameter will accept a single parameter only. If you need a value with more than one word then quotes must be used to prevent Rnews from splitting them into multiple parameters. -a Overwrites the configured name of the active file. -A Overwrite/adds an approval line. -c Sets the name of the configuration file. By default Rnews will use changi.cfg. -df Enables log file flushing. Should be specified for debugging only because this might dramatically increase your system load. -d Option '-df' is the only one currently working. -D This option allows you to specify the maximum geographic distribution of any post. -e This will override the default expiration date. -f This option specifies the article's sender. -F This option is used to attach a list of related articles which this message references to. -h ignored, but added for compatibility -N To submit an article to multiple newsgroups, the list must be separated by commas. -o This options is used to specify organization name. -r This parameter specifies the 'Reply-To:' line in the article header. -s Specifies the spool directory. -S Not implemented. -t Overwrites the 'Subject:' line in the article header. -y Overwrites the history file configuration item. ==================================================================== Expire Cleaning up ==================================================================== By default Expire scans the history file and uses the receive time recorded in it to purge old news articles. If called with the '-h' (ignore history) or '-r' (rebuild) option, Expire will use the active file to scan the newsbase. Expire makes its decisions on the time the article arrived, as found in the history file. This means articles are often kept longer than with other expiration programs that base their decisions on the article's posting date. Note, that Expire will keep the old history file while creating a new one. As history files might grow very large, enough disk space must be available. If in an emergency you should call Expire with the '-h' option. In this case the program will neither create a new history file nor touch the old one. Bugs ---- No locking supplied. Make sure that no clients are connected to Changi and Inews isn't running before calling Expire. The program has not been tested very well. Watch out for lots of bugs. Expire Command line options ==================================================================== Calling the program with the '-?' option will display a usage help: usage: expire [options] [newsgroups] newsgroups is a comma separated list of groups, which may include *, ? and [...] expressions options: -a active file -h ignore history -c configuration file -i ignore expire lines -e expire time -r rebuild -E forget time -n news directory -y history filename logfile flags: e log expiration progress f flush logfile after each line t test mode, do not really expire -a Overwrites the configured name of the active file. -c sets the name of the configuration file. By default Expire will use changi.cfg. -de Enables debugging output while expiring articles. -df Enables log file flushing. Should be specified for debugging only because this might dramatically increase your system load. -dt Enables test mode. All actions are performed like in normal mode, but no permanent modifications are done to neither the history files nor the active file and no articles will be deleted. -e Defines the expiration age. Articles received before the specified time will be deleted. -E Defines the maximum time to remember articles. Those received before the specified time will be removed from the history. -h With this option set Expire will ignore an existing history file and scan the newsbase using the active file. This is useful when the filesystem does not have sufficient space to hold both the old and new history files. -i This option will force Expire to ignore expire lines in article headers and will significantly decrease processing time. Do not use this option in conjunction with '-h' or '-r' unless you're sure about what you're doing. -n Overwrites the name of your local news directoy. -r With this option set Expire will scan the newsbase using the active file and build a new history file from scratch. -y overwrites the historyfile configuration item. newsgroups With this optional parameter you can limit the number of groups to process. It offers the possibility to apply different expiration times to different groups. Wildcards are accepted as follows. comp.os* matches every group starting with comp.os *tcp-ip matches every group ending with tcp-ip comp*tcp-ip this is possible too de.os[29] matches de.os2 as well as de.os9 de.os[2-9] matches previous and de.os3, de.os4... a?t.comp matches art.comp, alt.comp... !alt* matches every group excluding those starting with alt alt\!.\[x\] matches alt!.[x] ==================================================================== Shrink Shrinking files ==================================================================== This little program shrinks files to a given size, preserving the data at the end of the file. Truncation is performed on line boundaries, where a line is a series of bytes ending with a newline. There is no line length restriction and files may contain any binary data. A temporary file is created in the current directory. A newline will be added to any non-empty file that does not end with a newline. The maximum file size will not be exceeded by this addition. By default, files are truncated to zero bytes. The -s option may be used to change the maximum size. Because the program truncates only on line boundaries, the final size may be may be smaller then the specified maximum. The size parameter may end with a k, m, or g, indicating kilobyte (1024), megabyte (1048576) or gigabyte (1073741824) lengths. Uppercase letters are also allowed. The maximum file size is 2147483647 bytes. If the -v flag is used, then Shrink will print a status line if a file was shrunk. ==================================================================== UUPC Using with Changi ==================================================================== UUPC is a great UUCP package for OS/2, which is copyright by Kendra Electronic. Like Changi it is free and it comes with source. However, your newsfeed (internet provider) must support UUCP for news exchange. If you are new to UUCP and all this other UNIX-ish stuff, it will probably take some time to get it running smoothly. While you read through all the well done documentation that comes with UUPC (much better than the crap supplied with Changi) even many things related to Changi will become clearer. UUPC, at least starting with version 1.12j, contains another incarnation of Inews and Rnews too. Both, those that came with Changi and the ones with UUPC, should be interchangeable. Should... but unfortunately they are not. You may use any with UUPC, but you cannot use those with Changi, that came with UUPC. The reason for this incompatibility is the fact, that the UUPC versions of Inews and Rnews cannot be fed by the standard input but need a file instead. Hopefully this problem will be solved in the near future. If you use Changi's Inews with UUPC then you must set the '-U' option in your changi.cfg. This will force Inews to use the UUPC mangling mechanism for the spool file names. Otherwise Inews uses the standard naming like all those UNIX versions. You can find UUPC on the hobbes CD-ROM 03/95. Look for \32bit\comm\UPC12B??.ZIP or try ftp.hobbes.nmsu.edu for the latest version. ==================================================================== Problems In case of... ==================================================================== Reading documentation is a bit tedious, especially when you are short in time because there's a problem crying out to be solved. But news processing is relatively complex and effective troubleshooting requires that you understand what's going on. The investment of time is worthwhile. Anyway, I will provide some hints solving common problems. Problems with hostnames ----------------------- Remember to either use your ip-number as the NR/2 command line option, have any named server available and running or remove your etc\resolv and create a hosts file. Does your Changi.cfg really point to the correct paths? Check every entry. Chanx connection problems ------------------------- If Chanx will not connect to the newsserver on the remote host, but responds with chanx: could not open socket: Permission denied then something might be wrong with your tcp/ip setup. In this case try to ping your newsserver. ping If ping responds with something like 64 bytes from 193.102.134.1: icmp_seq=0. time=0. ms then at least your connection works. If you can't get a response and if ping reports 100% packet loss after pressing ctrl-c, then check your tcp/ip configuration. Try to telnet to your newsserver. telnet -p 119 If you get something like Connection refused then there is probably no newsserver running at port 119 on the remote host. Contact the news administrator of the remote host. It telnet works fine but if Chanx receives only error messages but no articles, call it with options '-dfrs' and look into the logfile to find out what's going on. Also try '-mr' if INN is installed on the remote site. Newsreader problems ------------------- Changi is very sensitive with it's input files. If your newsreader displays all groups but no messages to read, you should check two files, 'active' and 'history.pag', for compatibility. If you can't get any unread articles, then there is probably some incompatibility between Changi and your history file. Recreate them using the expire program. Posting problems ---------------- If everything seems to work fine but the articles posted on the local machine don't get sent to your neighbors, then you might have configured the Inews call wrong. Use 'inews' without any option to spool outgoing articles to be sent by Chanx. Instead use 'inews -U' if you intend to call uucico to transfer your news. Further Reading ======================================================================== Standards --------- Changi communicates with newsreaders and remote hosts according to standards described by RFCs. An RFC is a Request For Comment, a de facto standard in the Internet Community. It is a form of published software standard, done through the Network Information Center (NIC) at SRI. Copies of RFCs are often posted to the net and obtainable from archive sites. Current news-related RFCs include the following: RFC 822 specifies the format of messages; RFC 1036 uses this. RFC 977 specifies NNTP, the Network News Transfer Protocol. RFC 1036 specifies the format of Usenet articles. RFC 1123 amends RFC 822. Books ----- Like to read a book? I liked to read: Managing UUCP and Usenet by Tim O'Reilly and Grace Todino O'Reilly & Associates, Inc. ISBN 0-937175-93-5 This book covers most of UUCP and a bit of NNTP and how they work in their original UNIX environment. Nevertheless it is quite useful for news administration under OS/2. ==================================================================== History ==================================================================== 06/11/95 Version 0.8 Chanx did only save the first part of newsgroup lists longer than 256 characters in nntp.hostname. This bug has been fixed. Some NNTP servers seem to have problems with newsgroup lists with a length of about 256 characters sent by Chanx. The maximum size is now limited to 128 characters in the hope that these servers will no accept it. Due to a bug in the configuration validation Chanco insists on a HOSTNAME environment variable. This bug has been fixed. Changi now logs upto two parameters received with commands it ignores. 06/13/95 Version 0.8a Changi does now close the last accessed article when the client disconnects. Changi will now check the limit of 10000 articles when scanning a directory. 06/14/95 Version 0.9 Changing directories and drives presented a lot of problems. Changi is no more doing such masochism. After hunting a bug in the XOVER for several hours I found out that it was gone after switching of compiler optimisations. ==================================================================== Credits ==================================================================== Thanks to... ...Alex Chapman for his help with the missing expire. ...Bill Fugina for his testing and his suggestions. ...Brian Hampson for his endless patience with version 0.7. ...Terry Raymond for his comments on version 0.7. ...John Tibbetts for his help with the ihave protocol. ...Eran Tromer for his help with the 4OS4 problem. Code has been stolen from... ...B-News done by Rick Adams and others. ...C-News written mostly by Geoffrey Collyer and Henry Spencer. ...INN done by Rich $alz. ...Netnews 3.0 mainly done by Eric S. Raymond. ...NNTPD written by Stan Barber and others. ...UUPC, which is copyright by Kendra Electronic Wonderworks. Thanks, and have fun. Harald Kipp ==================================================================== EOF ====================================================================