UUUUSSSSEEEENNNNEEEETTTT VVVVeeeerrrrssssiiiioooonnnn BBBB IIIInnnnssssttttaaaallllllllaaaattttiiiioooonnnn Matt Glickman Computer Science Division Department of Electrical Engineering and Computer Sciences University of California Berkeley, California 94720 Revised by Mark Horton _1. _I_n_t_r_o_d_u_c_t_i_o_n This document is intended to help a USENET site install and maintain the network news software. Please ask ques- tions of the author or of Mark Horton, such questions will help to point out areas that need to be addressed here. The overall order of things to do is: (a) Find somebody to link up with. You need a network con- nection of some kind, for example ARPANET or UUCP. You cannot get a link to Berkeley, sorry. If you must use UUCP and have no connections, you must have at least a dialup and preferably a dialer, and find someone wil- ling to call your machine. The USENET directory may be helpful in finding some other site geographically near yours to hook up to. (b) Create a localize.sh script to make local changes to the makefile and defs.h files. (c) Compile the software using the _m_a_k_e command. (d) Su and type ``make install''. This will copy the files out to the right place and make directories containing most of the important files. It will configure you in with a connection to ucbvax via uucp links. This is undoubtably wrong, so you will have to configure links as needed. (e) After editing the configuration table, get your contact at the other end of the link to add you to their sys or .sys file. May 3, 1983 - 2 - (f) Post a message to the to._s_y_s_n_a_m_e newsgroup which should be set up to go only to the site you are linked to, as a test. Have the other person send a message to your system using the same mechanism. If this doesn't work, find the problem and fix it. (Please don't use net.test unless there is no alternative. It is almost always possible to use test, or to._s_y_s_n_a_m_e, or some local.test group, instead of net.test. (g) Fill out a USENET directory form and post a copy to the USENET newsgroup ``net.news.newsite.'' (h) Post the ``etiquette'' and ``tencmdts'' files (in the doc directory) to your ``general'' newsgroup with a long expiration date. Running ``rnews'' separately on each of these files will do. (i) It will probably be necessary to fix your uucp command to allow rnews, and to support the -z and -n options. _2. _I_n_s_t_a_l_l_a_t_i_o_n _2._1. _C_o_n_f_i_g_u_r_a_t_i_o_n Local configuration of the UUUUSSSSEEEENNNNEEEETTTT version B software requires you to edit a few files. Most importantly, the ddddeeeeffffssss....hhhh and MMMMaaaakkkkeeeeffffiiiilllleeee files must be created from their tem- plates ddddeeeeffffssss....ddddiiiisssstttt and MMMMaaaakkkkeeeeffffiiiilllleeee....****. You should create a shell script called localize.sh which copies the files and makes local changes to the copies. Even for a completely vanilla site, some changes will be necessary. For example, your script should choose between Makefile.v7 and Makefile.usg, and between postnews.v7 and postnews.usg. You should include the name of the local organization (MMMMYYYYOOOORRRRGGGG) and the uid of the local news super user (RRRROOOOOOOOTTTTIIIIDDDD). A sample local- ize shell script can be found in localize.sample. The most important parameters are: _2._1._1. _R_O_O_T_I_D The numerical userid of the person who is the news super user. This should not be set to 0. Normally it is set to the uid of the news contact person for the site. _2._1._2. _N__U_M_A_S_K Mask for _u_m_a_s_k(_2) system call. Set to something like 022 for a secure system. Unsecure systems might want 002 or 000. This mask controls the mode of news files created by the software. Insecure modes would allow people to edit the files directly. May 3, 1983 - 3 - _2._1._3. _D_F_L_T_E_X_P The default no. of seconds after which an article will expire. 2 weeks (1209600 seconds) is the default choice. _2._1._4. _D_F_L_T_S_U_B The default subscription list. If a user does not specify any list of newsgroups, this will be used. Popular choices are aaaallllllll and ggggeeeennnneeeerrrraaaallll,,,,aaaallllllll....ggggeeeennnneeeerrrraaaallll. _2._1._5. _T_M_A_I_L This is the version of the Berkeley _M_a_i_l program that has the -T option. If left undefined, the ----MMMM option to _r_e_a_d_n_e_w_s will be disabled. _2._1._6. _A_D_M_S_U_B This newsgroup (or newsgroup list) will always be selected unless the user specifies a newsgroup list that doesn't include ADMSUB on the command line. That is, as long as the user doesn't use the ----nnnn flag to readnews on the command line, ADMSUB will always be selected. This is usu- ally set to ggggeeeennnneeeerrrraaaallll. (The intent of this parameter is to have certain newsgroups which users are required to sub- scribe to. A typical site might require ggggeeeennnneeeerrrraaaallll.) _2._1._7. _P_A_G_E The default program for which articles will be piped to for paging. This can be disabled or changed by the environ- ment variable PAGER. If you have it, the Berkeley _m_o_r_e com- mand should be used, since the + option allows the headers to be skipped. _2._1._8. _I_N_E_W_S The full path name of the _i_n_e_w_s program for _r_e_c_n_e_w_s to fork. _2._1._9. _F_O_L_L_O_W_U_P This is the command used to internally post followups. It is not normally changed. _2._1._1_0. _R_N_E_W_S The name of the _r_n_e_w_s program (a link to _i_n_e_w_s) for _u_u_r_e_c to fork. Normally this is /usr/bin/rnews. Wherever you install it, it must be in uuuuuuuuxxxxqqqqtttt's default path, normally ////bbbbiiiinnnn::::////uuuussssrrrr////bbbbiiiinnnn. May 3, 1983 - 4 - _2._1._1_1. _N_O_T_I_F_Y If defined, this character string will be used as a user name to send mail to in the event of certain control messages of interest. (Currently these are newgroup, rmgroup, sendsys, and senduuname.) As distributed, mail will be sent to user uuuusssseeeennnneeeetttt. It is recommended you create such a mailbox (have it forwarded to yourself) if possible, since this makes it easier for another site to contact the site administrator for your site. If you are unable to do this (e.g. you are not the super user) you should change this name to yourself. _2._1._1_2. _D_F_T_X_M_I_T This is the default command to use to transmit news if no explicit command is given in the 4th field of the sys file. It normally includes uux with the -z option. You should install this mod to uucp at once, otherwise your users will start being bombarded with annoying uux comple- tion messages. However, you can turn this off to get news installed. _2._1._1_3. _U_X_M_I_T This is the default command used if the U flag is present in the flags portion of a sys file line. In this case, the 2nd %s refers to the name of a file in the news spool area, not a temporary file. It can usually only be used when local modifications are made to the uucp system, such as the -c option to uux. _2._1._1_4. _D_F_T_E_D_I_T_O_R This is the full path name of the default editor to use during followups and replies. It should be set to the most popular text editor on your system. As distributed, vvvviiii is used. _2._1._1_5. _U_U_P_R_O_G If this is defined, it will be used as a command to run when the sssseeeennnndddduuuuuuuunnnnaaaammmmeeee control message is sent around. Other- wise the command uuuuuuuunnnnaaaammmmeeee will be run. Normally, this program should be placed in LIBDIR. _2._1._1_6. _M_A_N_U_A_L_L_Y If this is defined, incoming rrrrmmmmggggrrrroooouuuupppp messages will not remove the subdirectories, but rather just remove the group line from your active file. You should have NOTIFY on if you use this. Note that on a USG system the subdirectory will not be removed anyway unless you have an unsecure (mode 777 directory) system. This is turned off by default to May 3, 1983 - 5 - protect you against accidental or malicious removal of an important newsgroup. _2._1._1_7. _B_A_T_C_H If set, this is the name of a program that will be used to unpack batched articles (those beginning with the charac- ter `#'). Batched articles normally are files reading #! rnews 1234 article containing 1234 characters #! rnews 4321 article containing 4321 characters etc. _2._1._1_8. _B_E_R_K_N_A_M_E If your site is connected into USENET over a Berknet link, specify the Berknet name of your site here. _2._1._1_9. _L_O_C_A_L_N_A_M_E Most systems have a full name database on line some- where, showing for each user what their full name is. Most often this is in the GCOS field of /etc/passwd. If your system has such a database, LOCALNAME should be left unde- fined. If not, define LOCALNAME, and articles posted will only receive full names from local user information speci- fied in NAME or ~/.name by the user. If you have a nonstan- dard GCOS format (not finger or RJE) it will be necessary to make local changes to fullname.c as appropriate on your sys- tem. _2._1._2_0. _I_N_T_E_R_N_E_T If your system has a mailer that understands ARPA Internet syntax addresses (user@domain) turn this on, and replies will use the From or Reply-To headers. Otherwise, leave it disabled and replies will use the Path header. _2._1._2_1. _M_Y_D_O_M_A_I_N When generating internet addresses, this domain will be appended to the local site name to form mailing address domains. For example, on system ucbvax with user root, if MYDOMAIN is set to ``.UUCP'', addresses generated will read ``root@ucbvax.UUCP''. If MYDOMAIN is ``.Berkeley.ARPA'', the address would be ``root@ucbvax.Berkeley.ARPA''. If your site is in more than one domain, use your primary domain. The domain always begins with a period, unless the local site name contains the domain; in this case MYDOMAIN should be the null string. May 3, 1983 - 6 - _2._1._2_2. _A_U_T_O_N_E_W_N_G If defined, any article that comes in with an invalid newsgroup will automatically cause the newsgroup to be created. In the past this was enabled, but now it is dis- abled to prevent typographical errors at sites running older versions of news that do not prevent postings with bad groups from creating newsgroups all over the network. It is recommended that this be left disabled, although a new site coming up without a complete active file may wish to run with it enabled for a few weeks. _2._1._2_3. _C_H_E_A_P Do not chown spool files to news. Used for obscure accounting reasons on some systems. _2._1._2_4. _O_L_D Define this if any of your USENET neighbors run 2.9 or earlier versions of B news. It will cause all headers writ- ten to contain two extra lines: Article-I.D. and Posted, for upward compatibility. Once all your neighbors have con- verted, you can save disk space and transmission costs by turning this off. _2._1._2_5. _U_N_A_M_E Define this if the uname system call is available locally, even though you are not a USG system. USG systems always have uname available and ignore this setting. _2._1._2_6. _G_H_N_A_M_E Define this if the 4.2BSD gethostname system call is available. If neither UNAME or GHNAME is defined, inews will determine the name of the local system by reading /usr/include/whoami.h. _2._1._2_7. _V_7_M_A_I_L Define this if your system uses V7 mail conventions. The V7 mail convention is that a mailbox contains several messages concatenated, each message beginning with a line reading ``From user date'' and ending in a blank line. If this is defined, articles saved will have these lines added so that mail can be used to look at saved news. _2._1._2_8. _M_Y_O_R_G This should be set to the name of your organization. Please keep the name short, because it will be printed, along with the electronic address and full name of the author of each message. 40 characters is probably a good May 3, 1983 - 7 - upper bound on the length. If the city and state or country of your organization are not obvious, please try to include them. If the organization name begins with a `/', it will be taken as the name of a file. The first line in that file will be used as the organization. This permits the same binary to be used on many different machines. A good file name would be `/usr/lib/news/organization'. For example, an organization might read ``Bell Labs, Murray Hill'', or ``U.C. Berkeley'' or ``MIT'' or ``Computer Corp. America, Cambridge, Mass''. There are other parameters that may be modified in ddddeeeeffffssss....hhhh, and they are described in the file. _2._2. _M_a_k_e_f_i_l_e There are also a few parameters in the MMMMaaaakkkkeeeeffffiiiilllleeee as well. These are: _2._2._1. _N_E_W_S_U_S_R This is the owner (user name) of _i_n_e_w_s. If you are a superuser, you should probably create a new user id (tradi- tionally nnnneeeewwwwssss) and use this id. If you are not a superuser, you can use your own user id. If you are able to, you should create a mail alias uuuusssseeeennnneeeetttt and have mail to this alias forwarded to you. This will make it easier for other sites to find the right person in the presence of changing jobs and out of date or nonexistent directory pages. NEWSUSR and ROOTID do not need to represent the same user. _2._2._2. _N_E_W_S_G_R_P This is the group (name) to which _i_n_e_w_s belongs. The same considerations as NEWSUSR apply. _2._2._3. _S_P_O_O_L_D_I_R This directory contains subdirectories in which news articles will be stored. It is normally /usr/spool/news. Briefly, for each newsgroup (say nnnneeeetttt....ggggeeeennnneeeerrrraaaallll) there will be a subdirectory /usr/spool/news/net/general contain- ing articles, whose filenames are sequential numbers, e.g. /usr/spool/news/net/general/1, etc. Each article file is in a mail-compatible format. It begins with a number of header lines, followed by a blank line, followed by the body of the article. The format has deliberately been chosen to be compatible with the ARPANET standard for mail documented in RFC 822. You should place news in an area of the disk with enough free space to hold news you intend to keep on line. May 3, 1983 - 8 - The total volume of news in net.all currently runs about 3MB/week. If you expirenews after the default 2 weeks, you will need about 6MB of disk space (plus some extra as a safety margin and to allow for increased traffic in the future.) If you only receive some of the newsgroups, or expire news after a different interval, these figures can be adjusted accordingly. Other newsgroup classes do not add much to the volume; fa.all accounts for only about 80KB/week, and btl.all+bell.all are only about 450KB/week. _2._2._4. _L_I_B_D_I_R This directory will contain various system files. It is normally /usr/lib/news. _2._2._5. _B_I_N_D_I_R This is the directory in which _i_n_e_w_s, _r_e_a_d_n_e_w_s, and _c_h_e_c_k_n_e_w_s are to be installed. This is normally /usr/bin. If you decide to set BINDIR to a local binary directory, you should consider that the rrrrnnnneeeewwwwssss command must be in a direc- tory that can be found by uuuuuuuuxxxxqqqqtttt, which only searches /bin and /usr/bin unless you modify uuxqt. _3. _F_I_L_E_S This section lists the files in LIBDIR and comments briefly what they do. _3._1. _a_c_t_i_v_e A list of active newsgroups. Automatically updated as new newsgroups come in. The order here is the order news is presented by rrrreeeeaaaaddddnnnneeeewwwwssss, so you can edit this file to put important newsgroups first. Each line of the active file contains two fields: the newsgroup name, and the highest local article number (for the most recently received arti- cle), separated by a space. Local article numbers begin at 1 and count sequentially within the newsgroup as articles are received. They do not usually correspond to local arti- cle numbers on other sites. The article number is always stored as a 5 digit number (with leading zeros) to allow updating of the file in place. _3._2. _c_a_e_s_a_r A program to do caesar decoding of rotated text, on a line by line basis. The standard input is copied to the standard output, rotating each line according to a static single letter frequency table. If an integer argument is given (e.g. 13), every line is rotated by that argument, without regard to letter frequencies. This program is invoked by the ``D'' readnews command, and may also be used with the ``13'' argument to encode material for posting. May 3, 1983 - 9 - _3._3. _h_e_l_p A list of commands printed when an illegal command is typed to rrrreeeeaaaaddddnnnneeeewwwwssss. _3._4. _h_i_s_t_o_r_y A list of every article that has come in to your sys- tem. Used to reject articles that come in for the second time (presumably via a different path). This file will grow but is cleaned out by the expire command. _3._5. _h_i_s_t_o_r_y._d_i_r,_h_i_s_t_o_r_y._p_a_g These two files are used on V7 systems as a hashed ver- sion of history, containing the message ID's of all articles in history. They are only used if -DDBM and -ldbm appear in the Makefile. _3._6. _l_o_g If present, a log of articles processed and error con- ditions is kept here. This file grows without limit unless cleaned out periodically, the trimlib script in misc can be invoked from /usr/lib/crontab daily or weekly to keep the log short. _3._7. _n_g_f_i_l_e A list of newsgroups that you can legally post to locally. Actually it's a pattern, so if you include aaaallllllll it will allow everything. You probably want to forbid ffffaaaa....aaaallllllll here. It is also possible to control what newsgroups you will accept from other sites using a different mechanism - see the section on the format of the ssssyyyyssss file. _3._8. _n_o_t_i_f_y If this file is present, it's contents will be taken as the name of the user to notify in case of a problem. If the file is empty, nobody will be notified. (This overrides the NOTIFY option in defs.h.) This is useful if one person administers several systems and does not want multiple copies of control message notifications. _3._9. _r_e_c_n_e_w_s A program which allows you to send mail to get news posted. You usually need to run sssseeeennnnddddmmmmaaaaiiiillll or ddddeeeelllliiiivvvveeeerrrrmmmmaaaaiiiillll to be able to use this. May 3, 1983 - 10 - _3._1_0. _r_e_c_o_r_d_i_n_g A list of newsgroup classes and file names to display recordings for. The recording feature is analogous to the recordings played in some areas when you dial directory assistance, trying to be annoying and make you think twice. Recordings on certain newsgroups are intended to remind the user of the rules for the newsgroup, or, in the case of a company worried about letting proprietary information out, reminding authors that anything they say is seen outside the company and so proprietary information should not be included. The file contains one line per recording. The line contains two fields, separated by a space. The first field is the newsgroup class (e.g. ``net.all''), the second field is the name of the file containing the recorded message. If the file name does not begin with a slash, it will be searched for in LIBDIR. Sample recording files can be found in the misc directory. _3._1_1. _s_e_n_d_n_e_w_s A program to send news internally from one computer to another. Useful if you use mail links to transmit articles. _3._1_2. _s_e_q The current sequence number for your system. Used to generate unique article ID's. _3._1_3. _s_y_s A list of all your neighbors, which newsgroups they get, and how to send news to them. The format is documented below. _3._1_4. _u_s_e_r_s A list of users that read news on your system. _3._1_5. _u_u_r_e_c A program to receive news sent by sssseeeennnnddddnnnneeeewwwwssss. _4. _S_e_t_t_i_n_g _U_p _L_i_n_k_s There are two basic types of links for exchanging news: those that use mail and those that don't. The ones that use mail are more indirect, yet more versatile while the ones that don't are simpler. The default is without mail so that is discussed first. May 3, 1983 - 11 - _4._1. _N_o_n-_m_a_i_l _L_i_n_k_s The basic theory behind a non-mail link is that the _r_n_e_w_s program is invoked on the remote system with the arti- cle being transmitted as the standard input. This is possi- ble on some networks, but the most common implementation is via the UUUUUUUUCCCCPPPP network. Using the _u_u_x(_1_C) command, the com- mand which is forked to the shell looks like: uuuuuuuuxxxx ---- ----rrrr ----zzzz rrrreeeemmmmooootttteeeessssyyyyssss!!!!rrrrnnnneeeewwwwssss <<<< aaaarrrrttttiiiicccclllleeee This is the default transmission method. In order to set up such a link, obviously a UUUUUUUUCCCCPPPP link with the remote system must be in effect. In addition, _r_n_e_w_s must be available and executable by _u_u_x_q_t on the remote machine. In most cases, this means that _r_n_e_w_s must be in /usr/bin so _u_u_x can find it. Also, /usr/src/cmd/uucp/uuxqt.c should be checked to make sure that rnews is an allowed command. Other networks that allow remote execution include the Berknet, BLICN (usend), many Ethernets, and the NSC hyper- channel (nusend). It is important, however, that a spooling mechanism be available. Otherwise, if system A tries to send an article to system B via a remote execution command, and B is down, the article could be lost. Spooling arranges that the system will try again when B comes back up. _4._2. _M_a_i_l _L_i_n_k_s When using mail to transmit articles, two intermediary programs are necessary. These are _s_e_n_d_n_e_w_s(_8) and _u_u_r_e_c(_8). The idea is that when system A wants to send an article to system B, the sys file on system A has an entry for system B such as: /usr/lib/news/sendnews -a rnews@B which runs _s_e_n_d_n_e_w_s on the article. The -a option specifies that the mail should be formatted for the arpanet. Sendnews packages the article and mails it to rnews@B. Somehow, the B system is expected to make sure that all mail to user ``rnews'' is fed as input to the program _u_u_r_e_c. This pro- gram unpackages it and invokes rnews. The best way to get mail to rnews fed into _u_u_r_e_c is to use sendmail or delivermail, if you are on a system running them. Create an alias in /usr/lib/aliases as follows: rnews: "|/usr/lib/news/uurec" and sendmail will handle it. If you do not have a facility for forwarding mail to a program, you can gimmick your mailer to watch for it (using _p_o_p_e_n(3S), this is easy) or, if you don't want to do any programming, you can have _c_r_o_n invoke uurec every hour with /usr/spool/mail/rnews as stdin. This solution is messier because uurec must potentially deal May 3, 1983 - 12 - with multiple messages, something that has never been tested. _5. _F_o_r_m_a_t _o_f _t_h_e _s_y_s _f_i_l_e To set up a link to another site, edit the ssssyyyyssss file in LIBDIR. This file is similar to the L.sys file of uucp. Each line contains four fields, separated by colons: (1) The system name of a site to which you forward news. Normally all systems you have links to will be included. You should also have a line for your own system. (2) The newsgroups to be forwarded to them. This is a pat- tern in the sense of a subscription. Generally, you will list classes of newsgroups, that is, using ``all'' for everything. A typical forwarding list for a new site would be net.all,fa.all,to.sysname where ssssyyyyssssnnnnaaaammmmeeee is the name of the remote system. In particular, you don't want to forward aaaallllllll since local newsgroups (those without dots) should not be sent. For the line describing your own system, this field describes the newsgroups your site will accept from remote sites. Thus, if another site insists on sending you a newsgroup you don't want, say nnnneeeetttt....jjjjooookkkkeeeessss, include !!!!nnnneeeetttt....jjjjooookkkkeeeessss here. (You will have to add -DRESTRICT to CFLAGS in your Makefile or this won't have any effect.) This measure is on top of AUTONEWNG, which will nor- mally prevent unknown newsgroups from being forwarded if disabled. RESTRICT allows certain newsgroups never to be forwarded even if recreated. (3) This field contains flags describing the connection. An A will indicate that the other site is running an A version of netnews. A B indicates a B version. Leav- ing it empty defaults to B. If you are reading this document, you have a B version. Some existing sites run A versions. If you aren't sure, ask your contact at the other site, with whom you should be talking to set this up anyway. The F flag indicates that the fourth field is the name of a file. The full path name of a file containing the article in SPOOL will be appended to this file. The L flag prevents transmis- sion unless the article was created on this site. (It is recommended that you feed an L link to a backbone site, to ensure that your submissions will be more likely to get to the entire network, even in the event of a local problem. Please make sure that a mail link exists too, so you can get replies.) The N flag can also be included here, indicating that mail should be May 3, 1983 - 13 - sent using the iiiihhhhaaaavvvveeee////sssseeeennnnddddmmmmeeee protocol described below. The U field arranges that the parameter to the optional %s in the command field to be filled in with a per- manent file name from SPOOL instead of a temporary cus- tomized file name. (4) This field is the command to be run to send news to the remote site. The article will be on the standard input. Leaving this field blank means an ordinary uucp link is being used, that is, the command defaults to uux - -r -z sysname!rnews The - option tells uux to expect input on stdin. The -z option is nonstandard - you should add it, see the minus.z* files in the uucp directory. It shuts off the annoying message you would otherwise get mailed to you telling you that your article was broadcast OK. To avoid using the -z option, change the source or put the uux command in the fourth field. The -r option tells uux not to start up a daemon right away. This turns out to ease the load on the system, at the expense of making news be transmitted a bit slower. The news will be sent when the next daemon is started, usually this means the next time mail is sent to or from your sys- tem. If this turns out to be unreasonably long, put a line in crontab to run /usr/lib/uucp/uucico -r1 every hour or so. Here is a sample sys file for a site ``myvax'' with connections to ``yourvax'' where myvax also passes news on to ``downstream''. We assume that ``myvax'' and ``down- stream'' exchange a local newsgroup class lng.all as well as the network wide newsgroups. News to ``downstream'' is batched. myvax:net.all,fa.all,lng.all:: yourvax:net.all,fa.all:: downstream:net.all,fa.all,lng.all:F:/usr/spool/batch/downstream _6. _P_o_s_t_i_n_g _M_e_t_h_o_d_s There are three ways to post news. The basic method is to use the iiiinnnneeeewwwwssss command: iiiinnnneeeewwwwssss ----tttt _t_i_t_l_e ----nnnn _n_e_w_s_g_r_o_u_p_s < _b_o_d_y_f_i_l_e This is the primitive used by other programs, and is not very suitable for humans. May 3, 1983 - 14 - A somewhat friendlier front end is ppppoooossssttttnnnneeeewwwwssss. This pro- gram will prompt you for the title, newsgroups, and distri- bution, then place you in the editor. (The system default EDITOR is used unless the environment variable EDITOR is set, overriding the system default.) The text should be typed after the blank line. The title and newsgroups are available for editing at the top of the buffer. Other header lines can be added, such as an expiration date or distribution. When you write out the file and exit from the editor, the article will be posted. Another method is to use mail. This can only be done on systems that allow mail to a given name to be fed into an arbitrary program as input. This is easily done with the Berkeley delivermail or sendmail program, and not with any other mailer the author is familiar with. (It may be possi- ble to painfully set this up with MMDF, provided the news- group name is no more than 8 characters long.) To use mail, set up an alias such as the following: net.general: "|/usr/lib/news/recnews net.general" Whenever a user sends mail to nnnneeeetttt....ggggeeeennnneeeerrrraaaallll, this starts up the given shell command which calls recnews with one argu- ment, the name of the newsgroup. You need to create one alias for each newsgroup, and to keep the list up to date as new newsgroups are created. RRRReeeeccccnnnneeeewwwwssss will in turn invoke iiiinnnneeeewwwwssss. Note that there are problems with recnews. There is no way to use it to post to multiple newsgroups without creat- ing separate articles (something frowned upon because it forces people to read the same thing more than once.) Also, there is no way to make the recording feature (to safe guard proprietary information) work when recnews is used. _7. _V_a_r_i_o_u_s _c_o_n_s_i_d_e_r_a_t_i_o_n_s _7._1. _S_u_i_d _b_i_t_s The current intended state of affairs is that _i_n_e_w_s runs suid NEWSUSR. The _r_e_a_d_n_e_w_s program does not need to be suid. This makes it possible to write your own interface to read news instead of using readnews. (As distributed, _i_n_e_w_s is also sgid. I know of no good reason for this.) _7._2. _M_o_d_e_s _o_f _S_p_o_o_l _D_i_r_e_c_t_o_r_i_e_s All the files should be writable by NEWSUSR. However, due to a glitch, you will probably have to make the SPOOLDIR and its subdirectories mode 777. It could be 755 except for one problem. When a new newsgroup comes in, _i_n_e_w_s will attempt to _m_k_d_i_r a new subdirectory of SPOOLDIR for the newsgroup. Since both inews and mkdir are suid, mkdir will May 3, 1983 - 15 - use the real uid instead of NEWSUSER when checking for per- missions, and if the directory isn't 777 the check will fail. Here are several alternatives if you don't want a 777 directory around: _7._2._1. _F_i_x _R_e_a_l _U_i_d If inews is always run from cron or by root, the real uid can be arranged to be root or NEWSUSR. This is a poor solution since it makes the local creation of new newsgroup require super user permissions, and is a potential security hole. If this approach is taken, care must be taken to insure that the owner of the created directory is NEWSUSR. _7._2._2. _C_h_a_n_g_e _t_h_e _K_e_r_n_e_l _i_n_e_w_s will do _s_e_t_u_i_d(_g_e_t_e_u_i_d()) before it forks the mkdir. If your system permits this call, there will be no problem. In particular, Berkeley 4.0BSD and later systems allow this. An alternative change to the kernel is to automatically stack uids: when an suid program is run, set the new real uid to the old effective uid. _7._2._3. _G_r_o_u_p_s You could have inews be sgid NEWSGRP and all files writable by the group. This approach has been tested and the problem turns out to be that the mmmmkkkkddddiiiirrrr command uses the aaaacccccccceeeessssssss system call to check permissions. Since aaaacccccccceeeessssssss uses the real gid, you run into the same problem. _7._2._4. _A_n_o_t_h_e_r _m_k_d_i_r You could create a version of mkdir that does less checking, and put it in a directory that can only be accessed by NEWSUSR (mode 700, owned by NEWSUSR). Have inews fork this mkdir. _7._3. _E_x_p_i_r_a_t_i_o_n _d_a_t_e_s To get articles to expire automatically, put a line in crontab to run ////uuuussssrrrr////lllliiiibbbb////nnnneeeewwwwssss////eeeexxxxppppiiiirrrreeee every night. This command deletes all expired news. The -a option causes all expired news to be archived under /usr/spool/oldnews. Sometimes news is not expired when it should be. Be sure to check that expire has permissions to unlink files, that it runs as a user that has a .newsrc, and that it is properly suid. You can manually invoke expire with the -v (verbose) option to find out what it's doing. Adding levels May 3, 1983 - 16 - of verbosity (e.g. -v6) will get more and more output. _7._4. _V_e_r_s_i_o_n _t_o _V_e_r_s_i_o_n Version B will understand incoming news in either ver- sion A or B format, automatically. Version B will generate either format, depending on the flag in the 3rd field of the sys line. Version A will not understand version B format. Thus, it is possible for two version B sites to communicate using version A format. This will work but is not a good idea, since the translation from B to A loses information (such as the expiration date) which will not be there when translated back to version B. News from versions A and 2.9 B do not conform to the USENET interchange standard. 2.10 supports the standard and will communicate with either A or 2.9 B news. A news is written (losing other header information) if A is in the flags for the system. If OLD is defined, 2.10 will write out headers with both standard (Date, Message-ID) and 2.9 (Posted, Article-I.D.) lines so that either B system will properly handle the article. Incoming news is recognized by the first letter (``A'' for A news), or the lack of an ``@'' in the From line (2.9). Missing fields are constructed as well as possible from the available information. _7._5. _P_r_e_s_e_n_t_a_t_i_o_n _O_r_d_e_r The order of the newsgroups listed in LIBDIR/active is the order the newsgroups will be presented in. Initially this will be directory order, but you can edit important newsgroups like general to the top. A recommended order to maintain your active file in is this: general local.general net.general net.followup local newsgroups, in alphabetical order net.all newsgroups, in alphabetical order junk fa.all, in alphabetical order test all.test to.all control _8. _C_o_n_t_r_o_l _M_e_s_s_a_g_e_s Some news systems will send you articles that are not for human consumption. They are messages to your news May 3, 1983 - 17 - system called _c_o_n_t_r_o_l _m_e_s_s_a_g_e_s. Such messages contain the Control: header. Older systems use newsgroups matching aaaallllllll....aaaallllllll....ccccttttllll, and this will still work, although the Control: header is preferred. Since the newsgroup name is used for distribution only, and is not checked to ensure it's in the active file, such newsgroup names can still be used. This makes it possible to post network wide control messages with nnnneeeetttt....mmmmssssgggg....ccccttttllll (or restricted broadcast such as bbbbttttllll....mmmmssssgggg....ccccttttllll) or messages for a particular system: ttttoooo....uuuuccccbbbbvvvvaaaaxxxx....ccccttttllll. Messages are cancelled, however, with a Control: line in a message to the same newsgroup(s) as the original message. A control message contains a command and zero or more arguments (much like a UNIX program). The subject of the article contains the command and arguments. The body of the article is usually ignored, although some messages can use it for additional text information. Control messages are not stored in SPOOL, rather they are acted on and discarded at once. _8._1. _i_h_a_v_e/_s_e_n_d_m_e Two control messages are iiiihhhhaaaavvvveeee and sssseeeennnnddddmmmmeeee. These mes- sages allow two participating sites to set up a link so that one site will tell the other site it has a given article and wait for a request before it actually sends it. The normal case is to send an entire article to a system, which con- sults the history file to see if the article has already been seen, and then throws it away if it's been seen before. Note that, since most messages are short anyway, experience has indicated that for ordinary UUCP unbatched communication, all ihave/sendme does is triple the load and slow down forwarding. Hopefully future code will allow ihave's with multiple message ID's in the body, and existing code in 2.10 understands such messages, but does not gen- erate them. So we advise that you don't use ihave/sendme for now. Use of these control messages can cut down on this wasted transmission, but if you have a polled UUCP connec- tion, they can slow down receipt of news due to polling delays. It is up to each connected pair of sites whether they want to use this protocol. The choice is controlled by the N flag in the sys file. In the case of a leaf node (one with only one neighbor) there is no advantage to this proto- col. Even if both sites are able to initiate a connection (have dialers or the link is hardwired) the -r option on the uux can cause 2 hour or more delays in propagating news. Since this protocol can triple the number of messages gen- erated, you should carefully evaluate your situation when deciding whether to use it. If transmission time and phone bills dominate your costs, and you are sending news to several sites, and large article bodies dominate the costs May 3, 1983 - 18 - (rather than the headers and the time spent by UUCP nego- tiating transmission) it is probably worthwhile to use ihave/sendme. If your costs are dominated by CPU load from UUCP, or if you send news to a site that cannot get it from anywhere else, you probably do not want to use this proto- col. The decision can be made independently for each site in your sys file. This pair works as follows: Site mmmmyyyyssssiiiitttteeee receives arti- cle <<<<111122223333@@@@aaaabbbbcccc....UUUUUUUUCCCCPPPP>>>>. It enters it locally and then broad- casts it to its neighbors. One of its neighbors is site yyyyoooouuuurrrrssssiiiitttteeee which has the N flag in the ssssyyyyssss file. So mysite sends an article on newsgroup to.yoursite.ctl with title ``ihave <123@abc.UUCP> mysite''. This control message has two arguments - the first (<123@abc.UUCP>) is the article ID of the article in question, the second (mysite) is the name of the site sending the article. The name of the newsgroup and the sys file control transmission of the article, nor- mally the sys file will read something like yoursite:net.all,fa.all,to.yoursite:BN: which will cause an article on to.yoursite.ctl to be transmitted. Yoursite receives the message and looks to see if it has seen it before. If it has, it throws the message away and stops. If it hasn't, it sends a message on to.mysite.ctl with title ``sendme <123@abc.UUCP> yoursite'' which is transmitted to mysite. (The two arguments to sendme are the article ID requested and the site to send it to.) Then mysite gets this message and actually transmits the article to yoursite. _8._2. _n_e_w_g_r_o_u_p This message has one argument, the name of a newsgroup to be created. This allows special action to be taken locally when a new newsgroup is created. It is generated by the -C option to inews. By default, the newsgroup is added to the active file and a directory is created, and mail is sent to the local contact advising that this has happened. See the routine ``c_newgroup'' in control.c if you want something different to happen. (Note that, although the body of the message contains a brief description of the pur- pose of the group, this body is usually thrown away by existing software.) _8._3. _r_m_g_r_o_u_p This message has one argument, the name of a newsgroup to be removed. It is used for network-wide cancellation of a newsgroup. If MANUALLY is not defined, it will remove the articles, directory, and active file line for the group. May 3, 1983 - 19 - There is a shell script rrrrmmmmggggrrrrpppp that does essentially the same thing as this message, but the shell script only removes the group locally. We recommend that you leave MANUALLY defined, and when you receive mail advising you of the dem- ise of the newsgroup, you run rmgrp by hand. This will prevent accidental or malicious removal of a good newsgroup. _8._4. _c_a_n_c_e_l This message cancels a given article. It takes one argument, the message ID of the article to cancel. It should be broadcast to the same newsgroup as the original article. _8._5. _s_e_n_d_s_y_s The sys file is mailed to the originator of the mes- sage. There are no arguments. This is used for making maps. Since your sys file is public information, you should not remove or change this control message. _8._6. _s_e_n_d_u_u_n_a_m_e The uuuuuuuunnnnaaaammmmeeee(1) program is run and the output is mailed to the originator of the message. There are no arguments. This is used for making uucp maps. If you do not run UUCP or have sites in your L.sys which are a secret, you may wish to edit this. Note that only the output of uuname is mailed, not the contents of L.sys (which news does not have access to anyway). If you do make a change, you should arrange that some mail still is sent out to the originator of the message, so he will know your site received it. See the code in routine c_senduuname in control.c. _8._7. _v_e_r_s_i_o_n The local version name/number of the netnews software is mailed back to the author of the control message. _8._8. _O_t_h_e_r _M_e_s_s_a_g_e_s Any unrecognized message will cause an error message to be mailed to the originator. Additional messages may be defined as time goes on, such as messages to automatically update directories or maps. You should be willing to go into the code (control.c) and add messages as they become standardized. _9. _M_a_i_n_t_e_n_a_n_c_e There are some things you should do periodically to keep your news system running smoothly. We hope to eventu- ally automate all or most of this, but right now some of it must be done by hand. May 3, 1983 - 20 - The hhhhiiiissssttttoooorrrryyyy and lllloooogggg files in your LIB directory will grow. You should make sure that they are cleaned up period- ically. The LIB/expire program will remove lines from his- tory corresponding to deleted articles, but it is a good idea to check the file every few months to make sure it is not going wild. Be sure not to completely lose your history file when you clean it up, in case another neighbor tries to send you an article you recently got. (If you only get news from one site it is safe to clean it out completely.) The log file is not automatically cleaned out by any netnews software, and will grow quickly. The misc/trimlib script can be installed in LIB/trimlib, and invoked weekly from /usr/lib/crontab. You should also clean out old newsgroups that are no longer active. To remove a newsgroup net.foo, you should do the following: First, remove the subdirectory SPOOL/net/foo. Second, remove the line net.foo from your active file. (It is no longer necessary to remove the net.foo lines from people's .newsrc files, because readnews will clean them out and reorder their files.) Here is a shell script to remove newsgroups: : rmgrp newsgroup ... cd /usr/spool/news for i in $* do echo removing $i rm -rf `echo $i | sed 's:\.:/:'` cp /usr/lib/news/active /tmp/rmg$$ sed /^$i /d < /tmp/rmg$$ > /usr/lib/news/active done rm /tmp/rmg$$ Note that clearing up UUCP constipation is another thing you'll have to do if you have flaky hardware or phone lines. If you have more than one connection, chances are that UUCP will get clogged up when one of your neighbors goes down for more than a few hours. Various spooling schemes are being worked on to help make the news/uucp sys- tem more robust, but one thing you can and should do, if you find your /usr/spool/uucp directory getting too big, is to install a subdirectory fix to UUCP. A quick and dirty ver- sion of this is available from Duke, which traps the open, creat, link, etc. system calls at the assembly language level and maps, for example, D.fooA1234 into D.foo/D.fooA1234. Since the C. and D.local directories still get big, in practice this can still create some big directories, but the directories tend to be a factor of 5 smaller, resulting in a factor of 25 improvement to speed (since a directory traversal for all files is quadratic on UNIX). Right now, UUCP is the weak link in netnews May 3, 1983 - 21 - distribution, and you should certainly keep an eye on it. _1_0. _C_r_e_a_t_i_n_g _N_e_w _N_e_w_s_g_r_o_u_p_s As system news administrator, you are able to create newsgroups. To create a newsgroup, first make sure this is the right thing to do. (Normally a suggestion is first posted to net.general,net.news.group for a net newsgroup, followups are made to net.news.group, it is established if there is general interest in such a group, and a name is agreed on.) Then someone creates it by typing the command iiiinnnneeeewwwwssss ----CCCC _n_e_w_s_g_r_o_u_p This will create the directory and active entry locally. It will also prompt you for a paragraph describing the group and start up an inews to post a newgroup control message announcing the group. This control message will be sent out on net.msg.ctl and other sites may have configured their systems to do something with these messages. A human read- able announcement is not made - you can post this to net.news.group if necessary. Someone should post a first article to the new news- group immediately. If this is not done, the empty directory for the newsgroup will cause cccchhhheeeecccckkkknnnneeeewwwwssss to believe there is unread news, because each user has no .newsrc line for that newsgroup. This command creates the group network-wide. It is then possible to submit an article to the group. You must be the super user to use the -C option to inews. (That is, your uid must match ROOTID. It is recom- mended that you change ROOTID to your own uid so you don't have to su to create newsgroups.) A new site should get the active file from their neigh- bor and use the mmmmaaaakkkkeeeeaaaaccccttttiiiivvvveeee....sssshhhh shell script to create the local directory hierarchy and active file. (The local active file will have 00000 for each newsgroup, since local numbers will start at 1 for the first article received in each newsgroup.) _1_1. _C_o_n_v_e_r_s_i_o_n _f_r_o_m _A _t_o _B If you are currently running version A on your system, note that B is incompatible with A. The files are stored in a different format (headers have mail like field names now). The directory organization is different (each newsgroup has a subdirectory of its own, and the file names are numbers rather than site.id pairs). There are no bitmap, uindex, or nindex files to be trashed (which articles have been read is stored in each users .newsrc file). The user interface is slightly different (news/netnews is now called readnews, news is posted using inews, subscription is done by editing May 3, 1983 - 22 - .newsrc, the sense of the -c option is reversed, news is presented in newsgroup order, the -a and -t options now probably need -x as well, and there are many minor changes). We decided not to provide a program to convert from version A to version B. Rather, the following strategy was adopted for conversion: (1) Install the new news in a different spool directory from the old one. For example, you can use /usr/spool/newnews. You can change to the standard name later if you want. Get it to work for local mes- sages. (2) Post an article to newsgroup ggggeeeennnneeeerrrraaaallll with the old news announcing the change. Make available documentation such as the accompanying paper ``How to Read the Net- work News'' to the users. This article will be the last one in the old news. (3) Chmod the old news directory to 555 to prevent any more news from being posted. (Actually, this will prevent the bitfile from being updated, so it may not be a good idea.) (4) Replace the old rnews program with the new rnews pro- gram. (5) Test it by having your neighbor send you a message. (6) Wait a reasonable period for everyone to have read the final article with the old news. Perhaps a few weeks is right. (7) Uninstall the old news. Users will have to invoke _r_e_a_d_n_e_w_s instead of _n_e_t_n_e_w_s to read news. Depending on your old method of posting, this could be changed too. (If you were using mail, it does not need to be changed.) They will also have to fix their sub- scriptions. In general, they can type netnews -s to see what they subscribe to on the old system, and then create a file in their home directory called .newsrc con- taining options -s _t_h_e_i_r _s_u_b_s_c_r_i_p_t_i_o_n The format of the subscription pattern matching is the same as in A except that ALL is replaced by all (change to lower case). Something along the lines of this could be used to automate this: May 3, 1983 - 23 - (echo -n "options -s" ; netnews -s | sed s/ALL/all/) > .newsrc _1_2. _C_o_n_v_e_r_s_i_o_n _f_r_o_m _2._9 _t_o _2._1_0 Conversion from 2.9 to 2.10 is not nearly as involved as an A to B conversion. The user interface does not change much, and the user .newsrc files are not affected. However, it is recommended that you do the conversion during a time when no news is received, so that incoming news will not get lost. One way to ensure this is to make /bin/rnews be a shell script which saves the article in /usr/spool/innews/$$ ($$ is the process id of the particular shell and will be unique for each article). The first step to conversion is to customize the sources. In the past, you had to take a fresh distribution and edit the defs.h file and Makefile to suit local prefer- ences. If you had many local changes, or didn't record the local changes, upgrading could be annoying. 2.10 provides a mechanism to automate these changes. Create a shell script in the src directory called localize.sh. (You can use localize.sample as a template.) This shell script should copy either postnews.v7 or postnews.usg to postnews, copy defs.dist to defs.h, and copy either Makefile.v7 or Makefile.usg to Makefile. It should chmod any files that need to be changed (often Makefile and defs.h) to a writable mode. Then it should invoke eeeedddd on the files, making any necessary local changes. The next step is to compile the software, with ``make''. It may be necessary to update the localize.sh file until you are satisfied with the compilation. Note that after any change to the Makefile in localize.sh, you should run localize.sh by hand. Otherwise, although make will run it for you, it will then continue to do the make with the old Makefile. When the software is compiled, you should run the cvt.dots.sh shell script, with the lib and spool directories as parameters. This will create the new hierarchical spool directory, and a new active file in LIB/nactive. Old news will be linked into the new hierarchy while leaving links in the old hierarchy. Now you can test ./inews, ./checknews, and ./readnews, to make sure everything works. The newsgroup ``test'' is good for this. The next step is to back up the old binaries (mv /usr/bin/inews /usr/bin/oinews, etc.) and to install 2.10 with ``make cp''. Move LIB/active to LIB/oactive and LIB/nactive to LIB/active. Once it is installed, any incom- ing news will be placed into the new hierarchy but not the May 3, 1983 - 24 - old one. The critical time window is between running cvt.dots.sh and installing the new software - any incoming news between these two points will appear in only the old hierarchy and be lost to the new software. If any signifi- cant time elapses here, you should divert rnews into a separate spool directory as described above. Finally, test things by posting articles to to.neighbor newsgroups and watching some incoming news, and announce the change to your users. May 3, 1983