home *** CD-ROM | disk | FTP | other *** search
- .Ch "The Interface Between C News And The Outside World"
- .Ix "outside world" interface
- .SH
- Intro and Generalities
- .PP
- C News relates to the ``outside world'',
- the system it is installed on, in a number of ways.
- This document attempts to enumerate them and explain what goes on.
- .PP
- In general,
- C News
- attempts to rely only on ``common basic Unix'',
- .Ix Unix dependencies
- and in particular it is not particularly BSD-specific or System-V-specific.
- Specifically,
- it makes no use of ornate locking mechanisms,
- silly interprocess-communication schemes,
- peculiar networking primitives,
- extensions to C,
- or other annoyances.
- .SH
- Directories And Userids
- .PP
- .Ix directories
- .Ix userids
- .Ix /usr/lib/newsbin
- .Ix /usr/lib/news
- .Ix /usr/spool/news
- Most of the components of C News live in \fI/usr/lib/newsbin\fR,
- with control files in \fI/usr/lib/news\fR and spooling areas
- (for current news, inbound traffic, and outbound traffic) in
- \fI/usr/spool/news\fR.
- See the document
- \fIDirectory Layout and PATH in C News\fR
- for elaboration on the structure,
- \fIFiles in /usr/lib/news (aka NEWSCTL)\fR
- for a summary of control files,
- and
- \fIConfiguration Mechanisms in C News\fR
- for how to change the locations of the directories.
- .PP
- There is an extensive subdirectory structure under \fI/usr/lib/newsbin\fR,
- with only a few heavily-used utilities in the top-level directory.
- In the following,
- programs not explicitly described as going elsewhere are all under there
- somewhere.
- .PP
- C News's spool areas and major control files need to be owned by a
- specific userid,
- normally \fInews\fR.
- (We believe that nothing except some of the Makefiles knows this name.)
- We suggest that this userid should not own anything else on the system.
- The programs in \fI/usr/lib/newsbin\fR can be
- owned by \fIbin\fR (or anyone else)
- except for those that need to be setuid.
- .Ix setuid
- (On our systems the non-setuid ones are owned by \fIbin\fR.)
- .SH
- Unix Utilities
- .Ix Unix utilities
- .PP
- C News requires a fairly complete Unix or equivalent.
- (We take no position on whether 4BSD, or System V, is Unix or not;
- our private opinion is that neither truly deserves the name any more,
- although we occasionally change our minds about which is less deserving.)
- .Ix Unix spelling
- (Note also that ``Unix'' is used here as an abbreviation for
- \fBThe UNIX Operating System\fR\(rg,
- a registered trademark of AT&T;
- we acquired our bad habits and incorrect capitalization from
- Unix [sic] documentation supplied by the Bell System in the mid-1970s.)
- .PP
- .Ix shell
- In particular,
- C News relies heavily on shell files.
- ``Shell'' here means,
- of course,
- the standard shell,
- written by
- Steve Bourne.
- .Ix "Steve Bourne"
- If your \fI/bin/sh\fR is not a Bourne shell or \fIvery\fR good imitation,
- you're in trouble.
- Note,
- in particular,
- .Ix shell Korn
- .Ix ksh
- that some old versions of the Korn shell differ from
- the Bourne shell in some important details of quoting behavior, and
- we \fIknow\fR this causes problems with C News.
- You need a standard shell.
- .PP
- To the best of our ability,
- all our shell files begin with ``#!\ /bin/sh''.
- As far as we know,
- nothing actually relies on being able to \fIexec\fR a
- shell file;
- that is,
- if ``#!\ /bin/sh'' is just a comment to your shell,
- that should be okay.
- .Ix shell C
- .Ix csh
- If your shell misinterprets it as a request to run the C shell,
- however,
- you're in trouble.
- Running the following might help:
- .DS
- .ft B
- for f in `find . \-type f \-print`
- do
- if test " `sed 1q $f`" = "#! /bin/sh"
- then
- ed $f <<'!'
- 1s/#!/: use/
- w
- !
- fi
- done
- .ft
- .DE
- .Ix shell comments
- If your shell doesn't know about ``#'' comments at all,
- again you're in trouble.
- We hope that no modern shell makes either of these mistakes.
- .PP
- We believe that none of our stuff relies on relatively modern shell features
- like shell functions or
- \fIgetopts\fR (as distinct from \fIgetopt\fR).
- .Ix shell builtins
- If \fItest\fR and \fIecho\fR are not built-in commands in your shell,
- efficiency will suffer
- but everything should still run.
- It's possible that a few obscure things will break if your shell does not
- support ``['' as a synonym for \fItest\fR,
- although we try to avoid this usage.
- .PP
- Within the shell files,
- C News
- makes heavy use of a wide variety of Unix
- utilities,
- .Ix sed
- .Ix awk
- notably \fIsed\fR and \fIawk\fR.
- Any \fIawk\fR should do;
- in particular,
- nothing needs the
- .Ix nawk
- .Ix awk new
- ``new \fIawk\fR''.
- Although we have tried to avoid it,
- it is possible that some things depend
- on \fIawk\fR recognizing ``\et'' inside strings,
- which very old \fIawk\fRs
- didn't.
- .PP
- If your Unix does not put all standard Unix programs in
- the standard directories\(em\fI/bin\fR and
- .Ix /bin
- .Ix /usr/bin
- \fI/usr/bin\fR\(emyou will need to modify C News's default PATH to include
- whatever bizarre directories are involved.
- See the \fIConfiguration Mechanisms\fR document for details.
- In particular,
- for some insane reason,
- .Ix 4BSD insanity
- .Ix /usr/ucb
- 4BSD relocated a few standard
- utilities like \fIwc\fR to \fI/usr/ucb\fR,
- which causes trouble
- (and not just to C News!).
- We simply put some links in \fI/usr/bin\fR to fix this on our systems,
- and this is what we recommend you do,
- but if you can't,
- you'll have to
- change the PATH.
- .PP
- .Ix mail
- Several parts of
- C News
- rely on being able to send mail to an administrative
- account
- (the name of which can be chosen;
- see \fIConfiguration Mechanisms\fR).
- The assumption is that a message,
- .Ix "RFC 822" mail
- without any RFC822 headers,
- can be piped
- .Ix /bin/mail
- into \fI/bin/mail\fR
- (or whatever \fImail\fR is first in the PATH)
- invoked with a single argument which is the addressee,
- and be delivered to the addressee's mailbox intact,
- possibly embellished
- with headers.
- That is,
- with news's standard PATH,
- if
- .DS
- .ft B
- echo "relaynews: hi there Joe" | mail joe
- .ft
- .DE
- does not result in the message ``relaynews: hi there Joe''
- arriving in the mailbox
- ``joe'',
- you're going to have to fake it.
- (Note that some BSD mailers run into trouble with the colon in the example,
- interpreting such a line as a header.)
- See \fIDirectory Layout\fR for insight on where to put a fake \fImail\fR
- so that C News components will use it rather than \fI/bin/mail\fR.
- .PP
- Similarly,
- several parts of
- C News
- .Ix hostname
- rely on being able to invoke \fIhostname\fR
- without arguments,
- and have it return a single word which is the name of the
- CPU the code is running on.
- Again,
- you'll have to fake it if you don't have \fIhostname\fR
- or if it outputs something strange.
- .PP
- .Ix compress
- Input reception and output batching both want to use the \fIcompress\fR
- data-compression program.
- \fICompress\fR has been published on Usenet and is shipped with many Unix
- systems these days,
- but if you don't have it,
- we recommend that you get
- it from your neighbors or the \fIcomp.sources.unix\fR archives.
- .Ix comp.sources.unix
- It is possible to configure
- C News
- so that it doesn't use \fIcompress\fR
- to compress news being transmitted,
- but you don't want to.
- \fICompress\fR is good and it is fast.
- .SH
- Libraries
- .PP
- .Ix libraries
- C News
- is mostly self-contained as far as libraries go.
- It does need some things that are not yet universal,
- like a full set
- of string functions (e.g. \fIstrtok\fR);
- .Ix functions string
- we provide reasonably portable versions of these for places that lack them.
- .SH
- Networking
- .PP
- (We're talking here about networking in the sense of NFS and all those fun
- things,
- not \fIuucp\fR or TCP/IP.)
- C News
- is designed to run on systems which consist of a conglomeration of
- machines on a local network,
- with only one of them acting as news server.
- Be warned,
- though,
- that if you're doing this,
- .Ix rsh
- .Ix "remote command execution"
- you need to have \fIrsh\fR
- or some reasonably equivalent way of executing a program on another CPU.
- If you've only got one machine,
- .Ix server
- .Ix files server
- just make sure you \fIdon't\fR have a \fI/usr/lib/news/server\fR file and
- forget the whole issue.
- .SH
- Highly System-Specific Things
- .PP
- .Ix dependencies system
- .Ix "system dependencies"
- There are two small utilities within
- C News
- that are inevitably highly
- system-specific and have a high probability of needing changes to match
- your system.
- Both normally live in \fI/usr/lib/newsbin\fR proper.
- .PP
- .Df spacefor
- \fISpacefor\fR is invoked by various components of C News to find out
- how much disk space is available.
- The space margins in it are ones we find reasonable, but you may need
- to adjust them.
- On an old System V system in particular
- (one where \fIdf\fR can't be applied
- to any directory name,
- but needs to be given a name in \fI/dev\fR),
- you
- will also probably need to modify the locations to be \fIdf\fRed.
- You will also need to fix \fIspacefor\fR if your system's \fIdf\fR yields
- results in some strange format or in some strange units.
- We believe that we get it right for stock 4BSD,
- many (but probably not all)
- System Vs,
- modern Irix,
- and real Unix (Version 7).
- .Ix Unix real
- .Ix Unix V7
- Beware introducing major inefficiencies:
- \fIspacefor\fR is called a lot.
- Beware,
- also,
- that \fIspacefor\fR is not intended to permit routine operation
- using filesystems that are on the brink of being full;
- the limits it imposes are only approximate,
- and no attempt has been made
- to tune its clients to exploit every last available block.
- .PP
- .Df queuelen
- \fIQueuelen\fR is invoked by the batcher to determine how long the current
- \fIuucp\fR queues are,
- so it can judge whether it should suspend batching
- of output to a given site.
- .Ix uucp
- There is too much diversity in \fIuucp\fRs for us to try to do this for all
- possible versions.
- We think we get it right for the two most common flavors
- (HDB, aka BNU, and old subdirectory versions).
- Our versions measure queue length in batches,
- not bytes,
- but it would not be hard to change this:
- \fIqueuelen\fR,
- .Ix batchparms
- the \fIbatchparms\fR control file,
- .Ix sendbatches
- and the \fIsendbatches\fR
- how-many-batches-should-I-try-to-add logic need to agree on the units of
- measurement,
- but (we think) nothing else cares.
- .PP
- .Df newshostname
- It is just possible that you might have to modify \fInewshostname\fR,
- which also lives in \fI/usr/lib/newsbin\fR itself.
- \fINewshostname\fR delivers the name which should be applied to the
- whole system (not just the particular CPU) for news purposes.
- It tries to be fairly clever about different ways of getting the name,
- and in particular will take it out of \fI/usr/lib/news/whoami\fR if
- .Ix whoami
- that file exists,
- but if you're doing something odd on a strange system,
- changes may be needed.
- .SH
- Input
- .PP
- .Ix input network
- .Ix "network input"
- Input from the net via \fIuucp\fR (or equivalent) shows up as batches of
- news to be fed to \fIrnews\fR or its obsolete synonym \fIcunbatch\fR.
- .Df rnews
- .Df cunbatch
- These two programs normally live in \fI/bin\fR,
- although nothing in the
- code knows about this and they can go elsewhere
- (one of our systems does this).
- .Ix newsspool
- Both are simple front ends that invoke \fIinput/newsspool\fR to store the
- batch,
- while taking precautions to report trouble and not to overflow disks.
- Neither \fIrnews\fR nor \fIcunbatch\fR needs to be setuid.
- .PP
- .Ix NNTP input
- Input via NNTP over the Internet (or equivalent) uses rather different
- machinery but ends up creating a saved batch in much the same way as
- \fIinput/newsspool\fR does.
- .PP
- .Df newsspool
- \fIInput/newsspool\fR is a small C program that saves a batch,
- writing into a file in \fI/usr/spool/news/in.coming\fR.
- .Ix in.coming
- It must be able to create files there, and \fIinput/newsrun\fR (see below)
- needs to be able to read them and delete them.
- .Ix newsrun
- This gets a little tricky because \fInewsspool\fR will usually be
- run by \fIuuxqt\fR as userid \fIuucp\fR (or something like that),
- not as \fInews\fR,
- which \fInewsrun\fR needs to run as.
- The recommended solution is to have
- \fInewsspool\fR owned by \fInews\fR and setuid.
- An alternative is to give the \fIin.coming\fR directory
- the userid of \fInews\fR and the groupid of \fIuucp\fR,
- or vice versa,
- and set permissions so that either can access it.
- One of our systems ran that way for a while.
- .PP
- .Df newsrun
- To actually process incoming news,
- \fIinput/newsrun\fR gets invoked
- to decompress the spooled batches and
- feed them to \fIrelay/relaynews\fR (see below).
- There is an option for \fInewsspool\fR to invoke
- \fInewsrun\fR when a batch is spooled,
- but a (usually)
- .Ix cron
- preferable method is to have \fIcron\fR invoke \fInewsrun\fR once an hour.
- \fINewsrun\fR does its own locking to prevent multiple occurrences running
- simultaneously.
- There is a related program,
- .Ix newsrunning
- \fIinput/newsrunning\fR, that can be used
- to set or clear a flag that stops \fInewsrun\fR;
- this may be a useful tactic if \fInewsrun\fR should not run at
- certain times.
- Both \fInewsrun\fR and \fInewsrunning\fR must be run as \fInews\fR.
- .PP
- When a user posts news,
- he (or his news reader) does it by feeding the
- article to \fI/bin/inews\fR.
- .Df inews
- In C News, \fIinews\fR is a complex shell file that attends to preliminaries
- and then invokes \fIrelay/relaynews\fR.
- \fIInews\fR does not need to be setuid (indeed,
- we make no use of setuid
- shell files at all,
- since they are grossly insecure).
- .Df relaynews
- \fIRelaynews\fR is the heart of
- C News,
- the program that actually pulls
- batches apart and places articles into the database.
- If users are to be able to post news,
- \fIrelaynews\fR should be owned
- by \fInews\fR and setuid.
- .SH
- News Readers
- .Ix "news readers"
- .PP
- C News
- is fully compatible with
- B News
- to any news-reader program that
- does not inspect the middle field of \fI/usr/lib/news/history\fR too closely.
- .Ix history
- Standard B News news readers work fine.
- We supply a simple news reader
- (written by,
- and included with permission of,
- Michael Rourke)
- as a naive-user replacement for the B News
- \fIreadnews\fR.
- .Ix "news readers" readnews
- More complex programs are preferable for serious news enthusiasts.
- We recommend
- Larry Wall's \fIrn\fR
- .Ix "news readers" rn
- or
- Kim Storm's
- .I nn
- .Ix "news readers" nn
- (which we use, unmodified),
- but there are others.
- .SH
- Output
- .PP
- \fIRelay/relaynews\fR normally queues up news for transmission to other
- systems by appending article names and sizes to batch files
- in subdirectories under \fI/usr/spool/news/out.going\fR.
- .Ix out.going
- These are then processed by \fIbatch/sendbatches\fR,
- .Df sendbatches
- which should be run
- regularly,
- as \fInews\fR,
- by \fIcron\fR.
- .Ix cron
- \fISendbatches\fR can be configured to use a variety of transmission
- mechanisms,
- the usual one being \fIuux\fR.
- .Ix uux
- .SH
- Expiry And Related
- .PP
- .Df expire
- .Ix article removal
- .Ix article archiving
- News articles are removed,
- possibly with archiving to an archive area,
- by the expiry subsystem.
- \fIExpire/doexpire\fR should be invoked now and then,
- .Ix doexpire
- as \fInews\fR,
- by \fIcron\fR.
- .Ix cron
- We suggest nightly.
- \fIDoexpire\fR actually invokes \fIexpire/expire\fR to do the dirty work.
- .PP
- C News \fIexpire\fR does not have an option to rebuild the
- \fI/usr/lib/news/history\fR file from scratch,
- .Ix history
- since that has nothing to do with expiry.
- To rebuild \fIhistory\fR,
- e.g. if it has been destroyed,
- use \fIexpire/mkhistory\fR.
- .Ix mkhistory
- .Ix history rebuild
- .PP
- Some news readers
- (notably the NNTP-based ones)
- need to have the third field of \fI/usr/lib/news/active\fR
- updated occasionally to show the lowest article number still present in each
- newsgroup.
- .Ix active "third field"
- .Ix files active
- Frankly,
- we think such news readers
- (and NNTP)
- simply need to be fixed.
- C News
- \fIexpire\fR does not do this updating.
- For those who use such news readers,
- however,
- \fIexpire/upact\fR will do
- such an update.
- .Ix upact
- It should be run as \fInews\fR.
- A much faster, but somewhat less portable,
- C implementation is
- supplied as \fIexpire/updatemin\fR.
- .Ix updatemin
- .SH
- Reboots and Administration
- .Ix reboots
- .Ix crashes
- .Ix lock
- .PP
- If the system crashes,
- things like locks must be cleaned out if C News
- is to function properly after reboot.
- \fI/etc/rc\fR,
- or equivalent,
- should run \fImaint/newsboot\fR during reboot,
- as \fInews\fR.
- .Ix /etc/rc
- .Ix newsboot
- .PP
- .Ix logs
- Certain log files can grow without bounds if not renamed/removed now and
- then.
- We recommend running \fImaint/newsdaily\fR once a day.
- .Ix newsdaily
- It tends to logs,
- keeping a generation or two for use in trouble tracking,
- and also sends mail to the news administrator in the event that something
- funny has happened.
- .PP
- In general,
- .Ix lock problems
- C News does not attempt to break locks,
- on the philosophy that a stale lock may mean something is badly wrong.
- (See
- \fILocking in C News\fR for details on locking methods.)
- The various programs will either give up,
- to return later,
- or wait
- patiently for the lock to go away.
- If one doesn't keep an eye on things, a problem of some kind can hang up
- the news system for quite a while.
- Running \fImaint/newswatch\fR once in a while\(emwe recommend a few times
- a day\(emwill alert administrators to signs of trouble.
- .Ix newswatch
- Except on grossly slow systems,
- C News locks should never hang around for
- any great length of time.
-