install.ms

早期freebsd实现

.\" $Revision: 1.13 $
.\" Uses the -ms macro package; e.g., "nroff -ms Install.ms | col >Install.out"
.\" UX - UNIX macro
.nr UX 0
.de UX
.ie \\n(UX \s-1UNIX\s0\\$1
.el \{\
\s-1UNIX\s0\\$1\(dg
.FS
\(dg \s-1UNIX\s0 is a registered trademark of Unix Systems Laboratories.
.FE
.nr UX 1
.\}
..
.DA "February 14, 1992"
.TL
Installing InterNetNews
.AU
Rich $alz
.AI
Open Software Foundation
11 Cambridge Center
Cambridge, MA  02142

\fIOrganization given for identification only;\fP
\fIplease send electronic mail to <[e-mail]>\fP
.AB
This document discusses how to install and set up InterNetNews.
You should be familiar with Usenet and networks; the first section gives
references to documentation for these topics, and the last appendix gives
a Usenet overview for novices.
.PP
This document also describes what many of the programs do and how they
should be used.
Even if you are a world-class expert at building and maintaining
public software, you should probably read this.
.PP
.de R$
This is revision \\$3, dated \\$4.
..
.R$ $Id: Install.ms.1,v 1.13 1993/03/19 17:49:59 rsalz Exp $
.AE
.NH 1
Things You Should Know Before You Do Anything
.PP
InterNetNews is abbreviated \fIINN\fP, which is pronounced
as the three letters, \fIeye en en\fP.
It is a Usenet transport and expiration system for larger
.UX
systems where NNTP is used for most Usenet traffic.
.PP
This document is not a tutorial on Usenet.
If you do not have much Usenet experience, you should read
\fIUsing UUCP and Usenet\fP, ISBN 0-937175-10-2.
You might also find it useful to read \fIManaging UUCP and Usenet\fP
(get the most recent edition available), ISBN 0-937175-48-X.
Both books are published by O'Reilly & Associates; send inquiries to
to <[e-mail]>.
.PP
You should know BSD-derived TCP/IP \(em at least be comfortable with host
names and dotted-quad addresses.
If you have installation problems, you should know about
.UX -domain
stream and datagram sockets and the like.
In addition to any documentation available from your vendor, you might
find it useful to read the two IPC tutorials in \fI
.UX
Programmer's Manual:  Supplementary Documents 1\fP.
Copies can be purchased from the Usenix Association; send inquiries to
<[e-mail]>.
.PP
There are two RFCs that are important to InterNetNews.
RFC 1036 describes the format of Usenet articles.
It is incomplete and has some errors, but it is the only formal
document available.
RFC 977 defines NNTP, the Network News Transfer Protocol.
RFCs are available from several places, including anonymous FTP
to nnsc.nsf.net, where they can be found in the directory \fIrfc\fP.
Both RFCs are currently being revised.
The 1036 revision is most likely going to be a ``tightening-up''; since
INN already has a strict interpretation of the RFC, this revision will
probably not affect InterNetNews very much.
The 977 revision is adding new features and facilities, and while INN
will not provide all of them, they will have some impact.
.PP
InterNetNews does things differently from other news software.
The most common Usenet systems for
.UX
are B2.11 and C News.
Both of them require a separate NNTP implementation.
The one everyone uses is called ``NNTP.''
Because this is confusing (they don't call \fIsendmail\fP ``SMTP''), I will
refer to it as the ``reference implementation.''
You generally do not need to know anything about these other systems,
but if you are curious, the official sites are as follows:
.DS
.ta \w'B2.11 News   'u +\w'ftp.cs.toronto.edu    'u
Package	Host	Directory
C\ News	ftp.cs.toronto.edu	pub/c-news
B2.11	ftp.uu.net	news/bnews-2.11
nntp	lib.tmc.edu	public
.DE
You might find the files \fIdoc/biblio\fP, \fIdoc/problems\fP, and
\fIdoc/rfcerrata\fP in the C News distribution worthwhile reading.
The first is a bibliography, the second discusses known C News porting
problems (see the DBZ sections in particular, and ignore most of the shell
comments), while the third lists some technical and philosophical errors
in RFC 1036.
.PP
The commands below assume that \fI$inn\fP is an abbreviation for the
top of the InterNetNews source tree.
.PP
INN could not have been written without access to the freely-redistributable
sources of B2.11, C News, and NNTP.
In particular, I want to thank Rick Adams; Geoff Collyer and Henry Spencer;
and Stan Barber, Erik Fair, Brian Kantor, and Phil Lapsley.
The financial support of UUNET Technologies is also greatly appreciated.
The beta-test sites gave invaluable feedback.
.NH 1
If You Are Impatient
.PP
If you don't want to follow these directions, do the following:
.DS
cd $inn/config
cp config.dist config.data
chmod 644 config.data
vi config.data (or emacs, or whatever)
cd ..
make world install
.DE
Then go read the appendixes.
If you have any problems, read the rest of this document.
.NH 1
Distribution Roadmap
.PP
The INN sources are divided into the following directories:
.IP \fIfrontends\fP 15
Programs to feed articles to the central server and control it.
.IP \fIinnd\fP 15
The central NNTP server.
It accepts incoming connections, receives articles, and arranges for
them to be sent to downstream newsfeeds.
.IP \fIbackends\fP 15
Programs to transmit articles to other sites.
.IP \fIexpire\fP 15
Programs to purge the article files and history database.
.IP \fInnrpd\fP 15
An NNTP server for on-campus clients that do newsreading (as opposed to
bulk article transfer).
.IP \fIlib\fP 15
Library routines used by all the above.
.IP \fIinclude\fP 15
Header files used by all the above.
.PP
The distribution also includes these directories:
.IP \fIsamples\fP 15
Prototype scripts and configuration files that might have to be edited
before they are installed.
.IP \fIsite\fP 15
A place to store edited copies of the files in the \fIsamples\fP directory.
.IP \fIdoc\fP 15
Manual pages for all the above.
.IP \fIconfig\fP 15
Tools to configure the release for your site.
.PP
Finally, there are a handful of files in the top-level directory:
.IP \fIREADME\fP 15
A basic introduction.
.IP \fICOPYRIGHT\fP 15
The distribution copyright.
InterNetNews is freely redistributable, provided proper credit is given.
.IP \fIMANIFEST\fP 15
A one-line description of every file in the distribution.
.IP \fIBUILD\fP 15
An interactive script to configure, build, and install INN.
.IP \fImakedirs.sh\fP 15
A script to build INN's directories.
As long as you have write permission to install the programs, this is
the only part of the installation that needs to be done as root.
.IP \fIMakefile\fP 15
Rules to call the other Makefiles and make distributions.
.IP \fIInstall.ms\fP 15
This document.
It requires the ``\-ms'' nroff/troff macro package.
.IP \fIMakeLib\fP 15
Script to build a directory with a replacement of the reference
implementation's ``clientlib'' routines needed by remote \fIrn\fP.
.IP \fIMakeInews\fP 15
Script to build an \fIinews\fP distribution directory.
.IP \fIMakeRnews\fP 15
Script to build an \fIrnews\fP distribution directory.
.IP \fIsedf.xxx\fP 15
Various \fIsed\fP scripts to filter the output of \fIlint\fP.
.NH 1
Building the System
.PP
INN is built in steps.
First, the \fIsubst\fP program is built.
Next, a configuration file containing key/value pairs is created.
\fISubst\fP reads this file and uses it to edit a specific set of files
in the INN distribution.
(Most of the files that get modified are Makefiles or header files.)
The library is then built; \fIlint\fP is usually a good way to see if
some of the basic configuration parameters are set up right.
The next step is to compile (and lint) all the programs.
The programs are then installed, and the INN data files are set up.
.PP
The configuration process is deliberately not interactive.
Configure scripts like the one in \fIrn\fP are fun to watch, but they
spend too much effort on the wrong job, like whether \fIgrep\fP returns
an exit status.
It is also difficult to change one parameter and rebuild the software.
(C News has this same problem.)
.PP
INN's method also has its flaws.
Because almost all configuration data is in one header file, changing
almost anything will force everything to be recompiled.
.NH 2
Building subst
.PP
INN uses the C News \fIsubst\fP program to automate the configuration.
\fISubst\fP is a very clever way of safely editing a file under the control
of a configuration file.
For more details, see the documentation in \fIdoc/subst.1\fP.
Thanks to Henry Spencer and Geoff Collyer for their permission to use and
redistribute \fIsubst\fP.
.PP
We will use \fIconfig.dist\fP as the configuration file to test the
version of \fIsubst\fP that you build.
.\"Using this file on your INN distribution should result in no changes to
.\"any files.
.\"If, while doing the steps below, you see any ``updated'' messages, then
.\"something is wrong with your distribution.
(You can always replace your config file with the distribution file and
do another \fImake\fP to restore the original versions.)
.PP
The C News \fIsubst\fP program is a shell script that uses \fIsed\fP to
do the editing.
The INN configuration file is too large for some versions of \fIsed\fP.
The first step is to see if your \fIsed\fP will work.
To do this, type the following:
.DS
cd $inn/config
cp config.dist config.data
make sedtest
.DE
If you get any error messages from \fIsed\fP such as ``too much command
text'' (or if it dumps core) you have two choices.
(You should also complain to your vendor.)
One choice is to use another version of \fIsed\fP, such as the one
distributed by the Free Software Foundation.
If you do this, edit \fIconfig/Makefile\fP and change the line that
defines the SED variable.
If you want to use the C News script, then do the following:
.DS
cd $inn/config
make sh
.DE
.PP
The other choice is to use the C version of \fIsubst\fP.
You might want to do this anyway, since it can be much faster.
To do this, type the following:
.DS
cd $inn/config
cp config.dist config.data
make c quiet
.DE
If you get any compilation errors, you will have to edit the file
\fIconfig/subst.c\fP.
If you are using an early version of AFS, you will have edit the file
to enable the USE_RENAME macro.
If you have to make any other changes, please let me know.
.PP
Since \fIsubst\fP changes source files, you might want to make a
backup copy of all the files that will be modified.
You can do this by typing ``make backup'' in the \fIconfig\fP
directory.
This will create a local tar file that contains all the files that will
be modified into it.
Doing ``make restore'' will unpacks the tar file.
(Since \fIsubst\fP makes its changes safely, this step is optional.)
.NH 2
Editing config.data
.PP
Once you have \fIsubst\fP working, the next step is to set up your
configuration parameters.
This is the hardest part of installing INN.
\fIDon't panic!\fP
There are many configuration parameters, but it should be very easy
for you to determine the answer for most of them.
To do this, you should copy \fIconfig/config.dist\fP, the distribution
master, to \fIconfig/config.data\fP, your local copy.
INN is distributed to compile and run under SunOS4.1 (without using
<unistd.h> and other POSIX facilities) by default.
.PP
The configuration file is divided into the following sections:
.DS
Make config parameters
Logging levels         
Ownerships and file modes
C library differences
C library omissions
Miscellaneous config data
Paths to common programs
Paths related to the spool directory
Execution paths for innd and rnews
Sockets created by innd or clients
Log and config files
Innwatch configuration
.DE
You should have a copy of \fIconfig.data\fP nearby as you read the next
few sections.
It is probably a good idea to write down your changes on paper before
you edit the file.
.PP
The format of the file is very strict.
A line starting with a poundsign is a comment line.
All other lines must be in this format:
.DS
parameter \fI<one-or-more-tabs>\fP value
.DE
If there is no ``value'' the ``<one-or-more-tabs>'' is still required.
Do not put quote marks around the values \(em if you do, you will usually
get a syntax error while compiling the system.
The discussion below uses quotes only to show where the values start and end.
.NH 3
Make config parameters
.PP
This section is used primarily to identify the path to your C compiler,
and what extra libraries or command-line switches are needed.
For example, you could put \fIgcc \-Wall\fP on the \fICC\fP line.
If you need extra \fI\-I\fP flags put them on the \fIDEFS\fP line.
INN uses the \fIregister\fP declaration a great deal.
If your compiler is very good, you might want to add \fI\-Dregister=\fP
to the \fIDEFS\fP line so that INN's declarations are ignored.
.PP
The DBZ package can be compiled so that the database is memory-mapped.
If you want to do this and have the \fImmap\fP system call, then add
``\-DMMAP'' to the \fIDBZCFLAGS\fP parameter.
.PP